跳到主要內容

建立 Bump PRD Hook 的認知調整歷程

已生成 9

從「以為 hook 什麼都能做」到「理解 hook 只是哨兵」的學習歷程——釐清 Hook、Slash command、CLAUDE.md 的分工，以及判斷該不該用 hook 的三個準則：不能漏、不需判斷、綁定生命週期事件。

更新於 2026/06/12

好的，以下是將標記穿插回原文後的完整版本：

建立 Bump PRD Hook 的認知調整歷程

從「以為 hook 什麼都能做」到「理解 hook 只是哨兵」的學習筆記

一、認知差異對照

示意圖 · diagram generated/hook-cognition-contrast.tsx
原本的認知
實際上的 hook
可以「偵測關鍵字」自動觸發
只在生命週期事件機械式觸發
可以做語意判斷
只能跑 shell script，沒有判斷力
可以呼叫 AI 來決定要做什麼
要 AI 判斷必須自己呼叫 API（需 API key、要付費）
應該「幫我做事」
Hook 是「哨兵」不是「執行者」
所有自動化都該用 hook
判斷給 AI、執行給 script、強制檢查才給 hook

最關鍵的誤解

把「使用者說 commit 就觸發」當成 hook 的工作。實際上那是 AI 在做語意理解，hook 只認得生命週期事件（SessionStart、Stop、PreToolUse 等），不認得「意圖」。

二、循序漸進的調整過程

時間軸 · timeline generated/hook-learning-journey.tsx
  1. 初始想法

    用 hook 在 git merge 時自動 bump 版號

    發現

    Hook 綁的是 Claude Code 生命週期，不是 git 事件；merge 自動 bump 該用 CI 或 git hook。

  2. 退而求其次

    Hook 偵測「我要 release」關鍵字自動 bump

    理解

    Hook 可注入 context，但判斷與執行是 AI 跟 slash command 的事；regex 關鍵字偵測會誤判漏判。

  3. 想全自動

    docs 改完後 hook 自己判斷該 bump 哪一位

    發現

    Hook 沒有 AI，要判斷得呼叫 Anthropic API——需 API key、要付費、引入不確定性、多 2–10 秒延遲。

  4. 關鍵轉折

    讓 AI 判斷後把版號當參數傳給 script

    理解

    Slash command 才是接收參數的正確機制，不是事件 hook；事件 hook 只能拿 JSON context。

  5. 流程修正

    綁在 commit 流程，AI 看 diff 後判斷

    發現

    觸發點對齊 git workflow，不需事件 hook 也不需 API key；AI 在 commit 前本就要看 diff，順手判斷版號是免費加值。

  6. 最終定位

    Hook 只當「忘記發版」的哨兵

    理解

    Hook 不執行 bump，只在 Stop event 檢查「docs 改了但版號沒動」用 exit 2 印提醒；職責切乾淨。

三、七種 Hook 事件

示意圖 · diagram generated/hook-lifecycle-events.tsx
SessionStartUserPromptSubmitPreToolUsePostToolUseNotification使用中StopSubagentStop

一次性檢查

對話結束時做一次性檢查，不會像 PostToolUse 那樣每改一個檔案就觸發。

避免無限迴圈

不會因為改了 PRD 又再次觸發自己。

時機自然

Claude 講完話的瞬間檢查，使用者剛好會看到提醒。

點擊節點查看說明
事件觸發時機我的使用
SessionStartSession 開始時—
UserPromptSubmit使用者送出訊息、AI 還沒處理—
PreToolUseAI 決定用工具、還沒執行—
PostToolUse工具執行完成—
NotificationClaude Code 要通知你—
Stop ⭐AI 結束回應時✅ 使用中
SubagentStop子 agent 結束時—

為什麼選 Stop event

  • 對話結束時做一次性檢查:不會像 PostToolUse 那樣每改一個檔案就觸發
  • 避免無限迴圈:不會因為改了 PRD 又再次觸發自己
  • 時機自然:Claude 講完話的瞬間檢查,使用者剛好會看到提醒

四、最終成果架構

示意圖 · diagram generated/bump-prd-architecture.tsx
判斷層
AI / CLAUDE.md SOP
  • -理解「commit / 發版」意圖
  • -跑 git diff 看變更
  • -依 SemVer 判斷 bump major/minor/patch
  • -寫 changelog summary
指令 / 參數
執行層
Slash command /bump-prd
  • -接收參數 <new_version> <category> "<summary>"
  • -機械式寫進 PRD 與 changelog
  • -可靠 deterministic 不依賴 AI 判斷力
觸發守門
守門員
Stop hook 哨兵
  • -對話結束時檢查「docs 有變更但 PRD 版號沒動」
  • -用 exit 2 印提醒讓 AI 轉達
  • -不執行 bump 只負責提醒

流程示意

正常流程

TEXT
改 docs → 說「commit」 → AI 判斷 → /bump-prd → commit

忘了發版時(哨兵介入)

TEXT
改 docs → 對話結束 → Stop hook 檢查 → 提醒「該發版」

五、Key Takeaway

視覺化 · free generated/hook-takeaway-quote.tsx
Hook 是哨兵，不是司令官。

它站在固定位置（事件）、看到固定情況（matcher）、做固定動作（script）——不思考、不判斷、不指揮，那是 AI 的工作。

判斷該不該用 hook 的三個準則

  1. 這件事「不能漏」嗎? → 漏了沒關係的事,寫在 CLAUDE.md 就好
  2. 這件事「不需要判斷」嗎? → 需要語意判斷的,給 AI
  3. 這件事「綁定在生命週期事件」嗎? → 使用者意圖驅動的,給 slash command

三個都 yes 才該用 hook。

示意圖 · diagram generated/hook-decision-tree.tsx

這件事「不能漏」嗎？

機制對照表

表格 · table generated/mechanism-comparison-table.tsx
機制對照
機制誰觸發做什麼
HookClaude Code 引擎（事件）機械式動作、守門
Slash command使用者或 AI 主動呼叫可帶參數的工具
CLAUDE.mdAI 每次讀（advisory）行為指引、SOP
SkillAI 依需要載入給 AI 用的知識/工具集
Git hook與 Claude 無關Git 觸發（commit/push 時）跟 Claude Code 無關
讀完這篇了嗎？
建立於 2026/06/12 建立-bump-prd-hook-的認知調整歷程.mdx