前言

這一篇來分享一下我自己 Mac 上最愛用的 Stats 吧。剛好最近從 M1 跳到 M5 了，雖然轉移工具幫我無痛轉移，但不知道為什麼 Stats 每次都轉移失敗，所以這套軟體幾乎是我新 Mac 第一個會去裝的軟體，所以這邊就來分享一下它能做什麼、怎麼裝、還有我自己的一些設定習慣。

如果你之前有看過我寫的 Mac 上裝軟體到底該用哪種方式？Homebrew、官網下載、curl 完整比較 或 關於我推的 Raycast 擴充套件，強化你的 Raycast！，那這一篇基本上算是同一個系列 — 都是我自己長期掛在 Mac 上的東西。

所以 Stats 是什麼？

照慣例，先簡單介紹一下 Stats 是什麼東西。

簡單來講，Stats 是一款 macOS 的系統監控工具，相較於活動監視器，它更完善且直覺一次性把你需要看的東西列出來，像是我就會三不五時注意一下 Mac 溫度、網路流量、記憶體用量等等。

而這一款軟體本身是 MIT 授權的開源專案，所以完全免費使用，沒有任何功能限制，也沒有廣告或付費升級的煩惱，基本上你也不用太擔心它在背後偷做什麼奇怪的事情，也不會只有你遭殃，畢竟超多人用的。

這邊也快速列出一下它能夠看的範圍：

神奇吧？這 Stats 還有提供 Remote 呢！對於專門放一台 Mac mini 在家裡跑 OpenClaw、Hermes 使用者來講，這個功能就非常實用，可以直接在 Menu Bar 上看到遠端機器的狀態，不用再開一個遠端桌面軟體去看。

雖然我個人還沒用過 Remote 就是了，但看了一下 Stats 官網 介紹是覺得滿棒的。

安裝 Stats

講了那麼多，所以該怎麼安裝呢？這邊我依然推薦 Homebrew 的方式。

只需要在終端機輸入以下指令就可以安裝 Stats：

1

brew install --cask stats

Note
Stats 是一個 GUI 應用程式，所以要用 --cask 來裝，不能用 brew install stats（不加 cask 的話 Homebrew 會去找命令列工具的 formula）。

如果你不想用 Homebrew 也沒關係，直接去 GitHub 的 Releases 頁 抓最新版的 Stats.dmg。

我最常開的幾個模組

接下來就來分享每一個模組啦～

CPU 模組

CPU 模組是我長期保持開著的模組，畢竟可以讓我即時看到 CPU 的使用率，讓我可以快速判斷「電腦現在在幹嘛」，特別是當電腦突然變慢的時候，第一個會想看的就是 CPU 是不是被吃滿了。

GPU 模組

我如果有跑 LLM 的話，我就會打開來看一下，畢竟 GPU 的使用率在這種情況下會非常明顯地飆高，這樣就可以知道是不是模型正在運算中，還是說其實它卡在某個步驟沒動。

記憶體模組

記憶體模組也是我長期會關注的點，畢竟記憶體不夠用的話，系統就會開始把一些東西丟到硬碟上去來做記憶體交換，這時候整體效能就會大幅下降。

Note
稍微講一下，macOS 的記憶體管理跟 Windows 不太一樣，它會把沒用到的記憶體拿去當 cache，所以你會看到 Memory used 很高，可是其實系統還有很多可用的空間。

硬碟模組

這我自己就很少看了，所以基本上都是關閉，除非我剛好要做一些需要大量讀寫硬碟的工作，才會打開來看一下。

感測器模組

感測器模組對於我來講非常的重要，畢竟我是拿 Air 居多，如果溫度沒有控制或關注的話，Mac 就會進入 Thermal Throttle（降頻）的狀態，這時候不管做什麼都會卡卡的…

而 Stats 的感測器模組可以讓我直接在 Menu Bar 上看到一些重要的溫度資訊，例如：

• CPU 各核心的溫度
• GPU 溫度
• SSD 溫度
• 電池溫度
• 主機板各區的溫度
• 整體功耗

比較需要注意的是，這個模組溫度只會在 Menu Bar 上看到。

網路模組

這也是我長期開啟的功能之一，畢竟網路有問題、跑的快不快，這個就是最重要的模組惹。

Note
公開 IP 的部分 Stats 是去打一個外部 API 才拿得到，所以如果你很在意隱私，可以在網路模組的設定裡面把這個關掉。

電池模組

嗯…如果你是 Intel 時期的 Mac，我認為這功能滿重要的，因為 Intel 時期的 Mac 相較於 Apple Silicon 的 Mac 來講，電池的表現跟健康度都比較不穩定，所以如果你是 Intel 的話，這個模組就很建議開著看一下。

藍牙模組

藍牙模組我就幾乎沒用過了，所以就…如果你發現藍牙不穩時，可以拿來看看。

時間模組

時間模組我自己也沒什麼使用過，但方便在於可以設定多個時區，這個對於需要跟海外時差合作的人來講會比較實用（吧）。

最多，我自己是會掛一個美西時間，方便看一些國外服務的維護時間。

額外小技巧分享

有時候因為 menu bar 的空間有限，所以我會把一些我核心注重的細節放在桌面上，你只需要點桌面右鍵 => 編輯小工具

接著找到你要拖曳放到桌面上的工具，然後直接拖曳到桌面上就可以了。

這樣就可以在桌面上看到一些更詳細的資訊了，像是我自己就會把 CPU、GPU、記憶體的使用率放在桌面上。

常見問題

接下來我也列出一下一些問題。

桌面小工具總是出現「No data available」的問題？

這個問題是因為你需要打開「macOS widgets」這個功能才有辦法顯示，因為 Stats 的桌面小工具是用 macOS 原生的 Widget 功能來實現的，所以如果你沒有打開這個功能的話，就會一直看到「No data available」的提示。

但這邊也要注意一下，開啟這個功能是會導致 Stats 一直針對硬碟做讀寫的，這個問題在官方 Issues 也有人提出過：Widgets do not update or high disk writes

桌面工具一直出現「Enable in Settings」的問題？

這方面其實我覺得一直都會發生，所以只能等官方修正了。

結語

最後就來總結一下吧。

所以我個人推薦使用的原因有以下：

• 開源、免費、MIT 授權
• 模組化設計，要看的才開，不要的關掉
• 畫面乾淨、支援中文
• 可以看到 macOS 原生不太願意給你看的東西，例如 CPU 溫度

所以希望這一篇對你有幫助哩～

前言

之前我有寫過一篇 SEO 已經不夠了嗎？認識 AEO 答案引擎優化 跟 從 3 分到滿分！讓你的網站通過 isitagentready，裡面有提到 /llms.txt 是用來告訴 AI 搜尋引擎你的網站有哪些東西的索引檔，然後這邊有個關鍵是你必須要把它的 Content-Type 標成 text/markdown。

那這邊我自己也乖乖把 /llms.txt 跟 /llms-full.txt 丟到 gh-pages 上，可是如果你這時候順便 curl -I 一下你會發現回傳的是…

1
2

HTTP/2 200
content-type: text/plain

所以這一篇就是要來分享我怎麼用 Cloudflare 的回應標頭轉換規則，把 content-type: text/plain 改成 text/markdown; charset=utf-8，而這整個過程不用寫 Cloudflare Worker，免費方案就夠用哩～

為什麼 /llms.txt 會跑成 text/plain？

這個問題其實很簡單，因為它的副檔名是 .txt（對，就是這樣而已）。

每個 web server 在回應靜態檔的時候，會根據副檔名查一張對應表（叫做 MIME 對應表）來決定 Content-Type 要寫什麼。GitHub Pages 用的是業界很通用的 mime-db 那一套，對應規則大概長這樣：

所以 .txt 結尾的檔案就會被標注成 text/plain，即使你裡面寫的是 markdown 格式，web server 也不會幫你看內容，它只認副檔名。

這時候應該又有一個疑問了：text/plain AI 還是讀得到啊，反正內容是 markdown，給它讀就好不是嗎？

對，AI 確實還是讀得到，可是這邊有兩個小問題：

1. 少了明確的格式信號： AI 拿到 text/plain 之後會把它當純文字處理，不一定會啟動 markdown 的解析邏輯，這導致標題、列表、連結這些結構就比較容易被當成一般文字看待，那就沒辦法發揮 markdown 格式的優勢了。
2. 有些工具會看 Content-Type 決定要不要拿： 像 Anthropic、OpenAI 的文件裡都有提到，建議站點在提供 markdown 內容時把 Content-Type 標成 text/markdown，這樣 AI Agent 看到的時候會更明確知道這是要給它看的 markdown 內容，會比較友善地把它當成 markdown 來處理。

所以 Content-Type 的調整就變得格外重要。

為什麼選 Cloudflare 回應標頭轉換規則？

我認為對「就只是想改 Content-Type」這種相對單純的需求來講，用 Cloudflare 的回應標頭轉換規則最簡單，更不用說我自己的網域本來就是託管在 Cloudflare 上（畢竟 gh-pages 本身也沒有地方讓你動 header）。

所以接下來，就來介紹一下該如何設定吧。

設定步驟

整個流程非常簡單，只需要幾分鐘就可以設定完了。

Step 1：進到轉換規則頁面

1. 登入 Cloudflare Dashboard
2. 選你要設定的網域（這邊以我的部落格 israynotarray.com 為例）
3. 左側選單點 規則 → 轉換規則
4. 找到 回應標頭轉換規則 那一欄，點右上角 建立規則

這邊選擇「回應標頭轉換規則」

Step 2：填規則名稱

規則名稱我這邊取 Set markdown content-type，方便我之後一眼看出來這個規則在幹嘛。

你也可以叫 llms.txt markdown header 之類的，反正隨你喜歡。

Step 3：寫比對條件

接下來這邊稍微有一點坑 XD

所以我個人建議直接使用 編輯運算式 模式比較好，然後把整段貼進去：

1

(http.request.uri.path eq "/llms.txt") or (http.request.uri.path eq "/llms-full.txt") or (ends_with(http.request.uri.path, ".md"))

這段運算式做了三件事情：

• 抓 /llms.txt
• 抓 /llms-full.txt
• 抓所有 .md 結尾的檔案（如果你有開「每篇文章對應一份 .md」這種設計的話）

所以你的畫面按完成之後應該會變成這樣：

Step 4：設定要塞的 header

接下來是最重要的一個步驟，請你往下到 則… 區塊，點 設定新標頭 按鈕，會展開三個欄位讓你填：

• 動作： 選「設定靜態」（Set static）
• 標頭名稱： 填 Content-Type
• 值： 填 text/markdown; charset=utf-8

charset=utf-8 這段建議加上去，不然中文內容在某些 client 上可能會出現編碼錯亂。

放置於 保持預設的「最後」就好，按右下角 部署 就完成啦～

Step 5：用 curl 驗證

部署完之後打開 terminal，跑一下 curl -I 看回應的 header：

1

curl -I https://你的網域/llms.txt

預期看到的回應大概長這樣：

1
2
3

HTTP/2 200
content-type: text/markdown; charset=utf-8
server: cloudflare

content-type 變成 text/markdown; charset=utf-8 就代表規則生效了。

Note
如果你看到 content-type 還是 text/plain，可能是 Cloudflare 邊緣快取還沒更新。可以加 -H "Cache-Control: no-cache" 重抓一次，或者直接去 Cloudflare Dashboard 的快取頁面點「清除快取」一下。

結語

最後總結一些重點吧。

1. 如果部署在 gh-pages 上，.txt 結尾的檔案預設會被標成 text/plain，這時候 AI 爬蟲就不太會把它當 markdown 來處理了。
2. 用 Cloudflare 的回應標頭轉換規則可以很簡單地把 /llms.txt、/llms-full.txt 和所有 .md 檔的 Content-Type 改成 text/markdown; charset=utf-8。
3. 設定的時候要注意比對條件的寫法，建議直接用編輯運算式的方式，這樣比較不會踩坑（要選「URI 路徑」不是「完整 URI」）。
4. 設定完之後可以用 curl -I 來驗證 header 是否有正確被改寫。

這條規則做完之後，下次 AI 爬蟲來抓 /llms.txt 就會拿到明確的 markdown 格式信號。

那如果你想做更進階的 Markdown Negotiation（也就是 AI 帶 Accept: text/markdown header 時，把整篇 HTML 文章即時轉成 markdown 回給它），那就要動到 Cloudflare Worker 了，這部分我之前在 從 3 分到滿分！讓你的網站通過 isitagentready 那篇有完整的 Worker 寫法可以參考。

到這邊整個 AEO 的最後一哩路就接起來了。希望這一篇有讓你對 Cloudflare 轉換規則有更近一步的認識哩～

前言

不知道大家有沒有遇過這種狀況，也就是昨天使用 AI 還感覺它很聰明，不用多講什麼就會順便把一些 Bug 給解掉，但隔天卻同樣的問題它打死都不回去主動順便把一些明顯的 Bug 給解掉，反而都要等你發現他才會處理，甚至它卻開始鬼打牆、答非所問，讓你開始懷疑「AI 是不是偷偷變笨了？」。

我相信這種感覺應該滿多人都有，但就是很難講出所以一個然。到底是 AI 廠商搞鬼，還是只是你今天的問題剛好比較難、或單純是心理作用？沒有一個客觀的數字，這就只是一個都市傳說。

所以這一篇就要來介紹一個網站，它就叫做AIStupidLevel，光看名字（直翻大概是「AI 智障程度」）就知道它走的是很直白的路線。它做的事情就是 24 小時不間斷地測試各家 AI 模型，幫你把「AI 是不是變笨了」這件事變成一條可以攤開來看的曲線。

所以我才寫一下這一篇來介紹啦～

所以 AIStupidLevel 到底是什麼？

簡單來講，AIStupidLevel 是一個「持續監測 AI 模型表現有沒有退步」的第三方評測平台，就跟我們系統在做健康檢查一樣，而它則是專門盯著 AI 模型的「健康狀態」，幫你抓出哪個模型最近偷偷變笨了。全年無休 24h 幫你監控 OpenAI、Anthropic、Google、xAI、DeepSeek、Kimi、GLM 共 7 家供應商旗下 21 個現役 AI 模型的表現，然後把每個模型當下的表現換算成一個分數攤在儀表板上。

這時候有些人可能會好奇，這個專案是不是某個 AI 監控公司做的，其實不是，這是一個開源專案。所以立場會比較偏向「第三方監督」角色，比較不容易跟廠商牽扯上關係，這點我覺得滿重要的，畢竟比較不會發生球員兼裁判的問題哩～

那麼了解了基本 AIStupidLevel 是什麼之後，讓我們繼續往下看吧。

恩？AI 為什麼會「變笨」？

我想這應該是滿多人會有的疑問，也就是…

模型出廠不是就訓練好了嗎？固定了嗎？

這個問題的答案其實原因有以下：

1. 無聲更新（silent update）： 你如果有接過 API 的話，你可能會看到這種版本號 （例如 gpt-4.0-20240924），其實這個版本號裡面那串日期（20240924）但實際上你在使用 Codex 選模型時，你並不會看到這麼細的版本號，甚至有些模型根本就沒有版本號，只有一個 model ID（例如 gpt-4），所以你根本不知道自己實際使用的是哪一版模型，被偷偷更新也很難察覺。
2. 量化（quantization）：許多時候，為了處理來自全世界的尖峰流量、算力，模型商可能會把模型壓縮過（量化）。
3. 算力限流：當使用人數超過一定之後的時候，模型商會把你能夠使用的算力限制掉，這樣就會讓模型的表現變差。
4. 算力移轉：有時候，當一個新模型即將推出的時候，模型商可能會把算力從舊模型轉移到新模型上，這樣就會讓舊模型的表現變差。以我自己長期接 API 來講，就很常遇到這種狀況，相同 Prompt 突然某一天彷彿降級到變成智障，接著沒多久模型商就推出更強的版本，接著舊版本才恢復正常。

其中「量化」這件事我之前在 想自己跑 LLM？搞懂模型參數與量化讓你不再選錯模型 那篇有比較完整聊過，簡單來講就是把模型壓縮的技術，壓縮過後雖然省資源，可是細節會少一點。

所以來畫個重點吧：

AI 模型不是一個固定不變的東西，廠商可能會在背後偷偷更新、偷偷量化、偷偷限流、偷偷轉移算力，這些都會讓模型的表現變差，但你卻很難察覺，所以才會有「AI 是不是偷偷變笨了」這種感覺。

它是怎麼測的？

講了那麼多，但似乎沒聊到 AIStupidLevel 到底怎麼測試的，其實核心測試方式很簡單，分別是：

1. 固定題目反覆考：它準備了一套固定的題庫，定時定期丟給各個模型去考，然後把成績記錄下來。
2. 同一題問 N 次：因為 AI 模型的輸出有隨機性，所以它同一題會跑 N 次，取中位數來當分數，並且算出 95% 的信心區間。

看起來很簡單吧？但魔鬼就藏在細節裡。

同一題問 N 次，因為 AI 每次答案都不一樣

「AI 每次產出都有隨機性不是嗎？」

沒錯，就是利用這個特性來設計測試的，如果只問一次就給分數，那絕對可信度是非長堤的，因此同一個題目至少會跑 N 次（但 N 是多少呢？AIStupidLevel 的做法是 5 次），然後取中位數來當分數，這樣就能比較穩定地反映出模型的「平均表現」，而不是被偶爾的好運或壞運給誤導。

四種測試輪流跑

AIStupidLevel 可不是只考一種題目，它可是準備了好幾套不同的測試輪流上場，每一套盯的東西不太一樣。整理成表格會比較清楚：

從這張表可以看出來，它的設計是「高頻快篩 + 低頻深測」搭配著用。每小時的快篩負責當哨兵，一發現苗頭不對就拉警報；每天那套比較重的深度推理跟工具呼叫，則是拿來做比較紮實的全面體檢。

其中工具呼叫那套我覺得特別有意思，它是真的開一個 Docker 沙箱（你可以想像成一個跟外界隔離的乾淨小電腦）讓 AI 在裡面實際跑指令，而不是只看它「嘴上說會不會」。這樣測出來的結果會比較貼近你實際拿 AI 來寫程式時的體感。

評分不是只看「對不對」

那一題到底怎麼打分數？這邊也是它做得比較細的地方。它不是單純看答案對不對，而是從好幾個面向一起評。

以程式碼解題來講，AIStupidLevel 目前是用 9 個面向加權算出來的，分別是正確性（40%）、複雜度（20%）、程式碼品質（15%）、穩定性（10%）、效率（5%）、邊界狀況處理（3%）、除錯能力（3%）、輸出格式（2%）、安全性（2%）。可以看到正確性佔了最大宗，但即使答案能跑，寫得又亂、邊界沒處理好、格式亂噴，分數還是會被扣。

怎麼抓出「變笨的那一刻」

光是有分數還不夠，因為分數本來就會上上下下的跳動（前面講過 AI 有隨機性）。真正的難題是：怎麼判斷這次掉分是「真的退化」，還是「正常的隨機跳動」？

這就是它最核心的技術了。它用了一個叫做 CUSUM 的演算法來偵測這件事。這個東西其實不是 AI 領域發明的，它本來是工廠在做品質管制時用的老方法，概念上就是持續累積「實際表現」跟「基準水準」之間的落差，當落差累積到一個程度，就判定「這不是抖動了，是真的出事了」。

除了 CUSUM 之外，它還會搭配統計檢定（去算這個差異在統計上是不是顯著、p 值有沒有低於 0.05）來再確認一次，盡量壓低「明明沒事卻亂報」的誤判率。

這邊真正的關鍵是：靠這套統計方法，它可以在模型開始退化的幾個小時內就抓到，而不是等到大家都在社群上哀嚎「AI 變笨了」才後知後覺。整個系統內建了 29 種不同的警告類別，對應各種不同的異常狀況。

那分數到底怎麼看？（Stupid Meter）

其實你打開網站就可以馬上看到儀表板了

每個模型旁邊都會有一個 0～100 的即時分數，分數越高代表當下表現越好、越「聰明」，你可以把它想像成 AI 模型的即時戰力錶。然後分數旁邊會掛上一個狀態標籤，告訴你它現在是 STABLE（穩定）、VOLATILE（在抖）、DEGRADED（已經降級）、還是 RECOVERING（正在回血）這四種狀態的哪一種。

除了當下的分數，它還會把每個模型的歷史曲線攤開，讓你比較「上週很穩的模型，這幾天是不是開始亂跳」這種情境，再搭配前面那 29 種警告類別，可以很快判斷現在這個時間點，哪幾個模型狀態正常、哪幾個最近怪怪的。

所以實際用起來，它比較像是看盤軟體，你不是來看一個死的排名，而是來看「此時此刻哪個模型最值得用」。如果你正在煩惱要選哪個 AI 工具，我之前寫的 2026 年 AI Coding 工具怎麼選？ 那篇可以搭配著看哩～

順便講一下 Smart Router

除了監測之外，AIStupidLevel 還附帶了一個叫做 Smart Router 的功能，這個我覺得是這個專案蠻有意思的延伸。

簡單來講，它就是一個 OpenAI 相容的 API endpoint（也就是你原本打 OpenAI 的程式碼幾乎不用改），你只要把各家 provider 的 API Key 存進去（會用 AES-256 加密），再把 base URL 換成它的網址，它就會根據當下監測到的模型狀態，自動幫你把 request 丟給最適合的模型。

它目前提供六種路由策略，你只要在打 API 的時候把 model 欄位指定成下面任何一個，它就會幫你動態挑模型：

• auto-best：通盤考慮，挑當下綜合分數最高的
• auto-coding：專挑當下程式題表現最好的模型
• auto-reasoning：專挑推理任務最強的
• auto-creative：偏向創意輸出
• auto-cheapest：在合格門檻內挑最便宜的
• auto-fastest：在合格門檻內挑回應最快的

如果你只填 auto，它會用你預設的策略；如果你填具體的模型名（例如 claude-opus-4-7），它就會直接打那個模型不走路由。換句話說，當某個模型偷偷變笨被它抓到時，Smart Router 會自動避開那個模型，把流量導去當下狀態還正常的兄弟模型，這對於要把 AI 真的接進產品的人來說滿實用的。

總結

聊那麼多，最後總結一下吧。

所以 AIStupidLevel 到底是什麼？

• 它是一個獨立、開源（MIT License）的第三方評測網站，24 小時監測 OpenAI、Anthropic、Google、xAI、DeepSeek、Kimi、GLM 共 7 家供應商旗下 21 個現役 AI 模型
• 測法是固定題目反覆考，同一題跑 5 次取中位數 + 95% 信心區間，分高頻快篩跟低頻深測四種套組輪流跑
• 它用 CUSUM 變點偵測搭配統計檢定，能在幾小時內抓出某個模型是不是偷偷退化了
• 另外還附帶 Smart Router，可以根據監測結果自動把 API 流量導去當下狀態最好的模型

下次你再覺得 AI 突然變笨的時候，先別急著懷疑是不是自己的問題，可以打開這個網站看一眼，搞不好真的能找到證據哩～

前言

之前寫過一篇 SEO 已經不夠了嗎？認識 AEO 答案引擎優化 ，寫完之後我突然有一個想法，也就是：AI 在做網路搜尋的時候，到底會撈走我部落格多少內容？整篇一字不漏？前面 500 字？還是只看到標題就跳走？所以就稍微研究一下，然後這篇就把 Anthropic 官方的 web_search 跟 web_fetch tool 文件翻一遍，順便拿自己的部落格實測一輪，最後整理這對怎麼寫文章、寫文案有什麼具體的影響吧。

先講清楚，「搜尋」跟「撈取」是兩件事

在我們開始往下之前，我認為必須要先把一件事情講清楚，也就是 AI 在做查詢時，「搜尋」 跟 「撈取網頁內文」 不是同一件事，它是兩件事情，而且是分層了兩階段來處理。

• 第一階段 （WebSearch）：AI 拿著你的問題去呼叫 WebSearch 工具（去查搜尋引擎），這時候回來的會是一份搜尋結果清單，每一筆資料都有網址、標題之類的資訊，可是不包含網頁的整篇內文。
• 第二階段 （WebFetch）：AI 看完搜尋結果清單之後，開始決定哪幾筆是它值得深入去看，接著再對那幾個網址各使用 WebFetch 工具發一次「把這個頁面的內文給我」的請求，這時候才會真的把內文撈回來。

嗯？你是不是好奇為什麼它不是直接在搜尋階段就把內文一起撈回來？

其實最大問題還是在於 Context （上下文）的限制上，你可以思考一下，如果它每次搜尋就把 10 筆的搜尋結果＋內文都塞進來，那想當然你可以使用的 Context 就很容易爆掉，然後接著你就會開始抱怨 AI 很笨、不記得剛剛的提問（畢竟 Context 爆掉了）。所以它才會把這兩件事分成兩階段，先搜尋拿到一個「清單」，然後再決定要從清單裡面挑哪幾筆去撈內文。

這邊我也順手畫一張流程圖，把兩階段的時序串起來看一眼會更直觀：

了解兩階段的差異之後，接下來就分別來看每個階段實際撈到了什麼。

WebSearch 撈到了什麼？

直接看 Anthropic 官方 web_search tool 文件，每筆搜尋結果裡面只有四個欄位：

• url：網頁的網址
• title：網頁的標題
• page_age：網頁上次更新時間
• encrypted_content：加密內容，這個不是給 AI 讀文章用的，是多輪對話時拿回來做 citation 用的

是的，就這樣，就這四個。

AI 在搜尋階段（WebSearch）看到的就是「網址、標題、上次更新時間」這三筆人類可讀的資訊，沒有任何內文。

那如果 AI 引用你的內容呢？也有上限

每個 web_search_result_location 的 cited_text 最多是 up to 150 characters of the cited content

簡單來講就是：最多 150 個字元的引用文字。而這些還只是 API 層級的規格而已。

Claude Code 內建的 WebSearch 又再砍一刀，根據 Mikhail Shilkov 拆解 Claude Code 內部行為的這篇文章 裡面有提到…Claude Code 連 page_age 跟 encrypted_content 都丟掉了，只保留 title 跟 url。

所以簡單來講…在搜尋這個階段 AI 看到你網站的東西就是只有 一個標題加一個網址 沒了。

WebFetch 撈到了什麼？

那接下來就要來聊一下，內文何時會被撈出來了，也就是前面有提到的，第二階段 WebFetch。

AI 看完搜尋結果之後，如果決定點開某幾筆，會對每個網址發一次 WebFetch 請求，這時候才會把整篇內文撈回來。那撈取範圍多大？

這邊需要分成兩層來說明，因為 API 跟 Claude Code 的設計不太一樣。

Note
這邊講的 API 是指 Anthropic API 的 web_fetch tool，Claude Code 是指 Anthropic 自己的產品線裡面內建的 WebFetch 功能，兩者的規格跟流程不太一樣。

API 層級的 web_fetch

Anthropic API 的 web_fetch tool 有一個叫 max_content_tokens 的參數，可以由開發者自己設定，雖然官方文件範例用的是 10 萬 tokens。

但官方文件上也有給參考換算：

由此可知，一篇中長度的中文部落格文章純文字通常 1~2000 tokens 就非常足夠了，遠遠低於 10 萬的上限。所以不太會發生「內文被截斷」的問題，除非你寫了一篇五萬字的超長文章（紅樓夢之類？）。

但這邊要特別注意，web_fetch tool 的 citation 跟 web_search 的設計不太一樣，它是使用 start_char_index / end_char_index 選出文章中的特定位置（雖然文件沒寫死字元上限就是了）。

Claude Code 內建的 WebFetch

Claude Code 內建的 WebFetch 走的是另一個方式。

依照 Mikhail Shilkov 的拆解， WebFetch 它的流程會是這樣的：

1. 把 HTML 用 Turndown 套件轉成 Markdown
2. 擷取內文的 100 KB 純文字
3. 把這 100 KB 丟給 Haiku 3.5 模型
4. Haiku 根據你給它的 prompt 摘要出答案，再把摘要回傳給主模型

這邊其實真正的關鍵還是在第三步驟，你會發現我們主模型（也就是我們當前使用的 Claude 模型）並不會直接看到網頁的原文，它都是看到 Haiku 摘要過的版本。也就是說，你寫的東西最後變成什麼樣回到主模型，是 Haiku 怎麼讀的決定，不是你寫了多少的決定。

而且引用部分也有限制，Mikhail 從 Claude Code 內部 prompt 抓到的規則是 Enforce a strict 125-character maximum for quotes from any source document，也就是說引用的部分最多只能有 125 個字元。

這時候應該又有一個疑問了，所以 100 KB 的純文字大概是多少呢？
假設以中文來說，每個字算 3 bytes 的話，100 KB 大概可以裝 3 萬多字；如果是英文，每個字算 1 byte 的話，可以裝十幾萬字。對於一個普通部落格文章來講，再長也撐不到這個量了。所以真正該關注的點應該是「怎麼讓 Haiku 摘到我想被引用的內容」，而不是「我寫了多少內容給 Haiku 看」。

拿我的部落格實測一輪

講了那麼多，這邊我們就來實際測試一下吧！

我這邊是直接請 Claude 呼叫 WebFetch 工具，然後把我部落格首頁（israynotarray.com）的 URL 給它，讓它去抓內文。

那麼該怎麼實際測試呢？我們可以善加利用 Hook 的特性，將每一個階段的輸入輸出都記錄下來，這樣就能清楚看到 AI 在每個階段實際撈到了什麼內容。

底下是我的 Hook 設定，這樣每次 WebSearch 跟 WebFetch 的輸入輸出都會被記錄下來：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "WebSearch|WebFetch",
        "hooks": [
          {
            "type": "command",
            "command": "/claude-tools/hooks/log-web-tool.sh"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/claude-tools/hooks/dump-transcript.sh"
          }
        ]
      }
    ]
  }
}

這邊我提示詞（Prompt）是以下：

1

請你幫我用 WebFetch 工具抓一下 israynotarray.com 首頁的內容，然後告訴我你從這個頁面摘了什麼內容回來。

實際 Input 內容如下：

1
2
3
4

{
  "url": "https://israynotarray.com",
  "prompt": "請告訴我這個首頁的主要內容：站名、站長介紹、最新文章列表（標題與簡介）、分類、以及任何導覽列或側邊欄資訊。"
}

接著跑完之後，你可以看到 WebFetch 的結果裡面，AI 摘要回來的內容大概是這樣的：

1
2
3
4
5
6
7
8

{
  "bytes": 1068,
  "code": 200,
  "codeText": "OK",
  "result": "# 網頁內容分析\n\n基於提供的內容片段，我能提供以下資訊：\n\n## 站點結構\n- **主要分類**：AI 相關內容，包括 Gemini 和 Gemini Omni 產品\n\n## 最新文章\n**標題**：「Gemini Omni 影片生成怎麼用？30 個 Reels、產品 Demo、Logo Reveal 提示詞模板」\n\n**簡介摘要**：\n本文介紹了 Google 在 2026 年 5 月 I/O 發布的 Gemini Omni 影片生成功能，說明其如何取代先前的 Veo 3.1。文章涵蓋「一次 10 秒短片、原生同步音訊、中文文字渲染」等新功能，並提供 30 個實用提示詞模板，適用於 Instagram Reels、產品演示、Logo 動畫、B-roll、轉場效果、引言卡片、生活風格與美食旅遊等多種場景。\n\n**發布日期**：2026-06-06  \n**閱讀時間**：約 23 分鐘\n\n## 限制\n提供的內容片段不含站長介紹或完整導覽列資訊。",
  "durationMs": 4603,
  "url": "https://israynotarray.com"
}

發現了嗎？你真正被 AI 撈走的內容其實只有這一小段 1000 字以內的摘要而已，一個網站裡面根本不可能只有這麼一小段內容，剩下的部分根本沒有被 AI 看到。也就是說中介層的 Haiku 模型看完之後，只挑了它認為跟我 prompt 相關的部分摘給我。同樣的頁面如果我用瀏覽器打開，看到的會是一整列文章卡片加 sidebar，可是 Haiku 不會把整列丟回來。

我順便試了一篇舊文，故意把 URL 路徑的某段寫錯，它就只會回傳這樣：

1
2
3
4
5
6
7
8

{
  "bytes": 0,
  "code": 404,
  "codeText": "Not Found",
  "result": "The server returned HTTP 404 Not Found.\n\nThe response body was not retrieved. If this URL requires authentication, use an authenticated tool (e.g. `gh` for GitHub, or an MCP-provided fetch tool) instead of WebFetch.",
  "durationMs": 588,
  "url": "https://israynotarray.com/dqwdqwdqwd"
}

你會發現連你寫在 404 頁面的內容都撈不到，因為 WebFetch 直接回報了 404 Not Found 的錯誤，AI 根本沒辦法看到你 404 頁面上寫了什麼內容。也就是說，如果你的網站有任何路徑問題、重構過 URL、或者只有前端路由沒有實體頁面，AI 就撈不到內容了。

順帶一提，這部分跟 Claude 官方文件裡的注意事項也對得起來：

The web fetch tool currently does not support websites dynamically rendered with JavaScript.

如果你的部落格是用前端 SPA 撐起來、內容完全靠 JavaScript runtime 渲染的話，那 AI 撈到的可能只是空殼 HTML，看不到任何文章。因此使用靜態產生器（像 Hexo、Astro、Next.js 的 SSG 模式）相對安全，因為 build 出來的就是完整 HTML，AI 一抓就有東西看（歡迎加入 Hexo 行列）。

robots.txt 那層也別忘了

接下來還有一個重點，AI 撈不撈得到你的網站，有一個大前提，也就是 robots.txt。

AI 爬蟲基本上分兩種：搜尋型（會引用 + 連回你網站）跟訓練型（吃內容餵模型，不一定有回引）。常見的對應大概長這樣：

如果你希望被 AI 引用、可是不想被拿去訓練，最常見的策略就是「搜尋型放行、訓練型擋掉」。

這邊我也給你一個可以直接複製貼上使用的 robots.txt 範例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# 搜尋型 AI 爬蟲：放行（會回引）
User-agent: OAI-SearchBot
Allow: /

User-agent: ChatGPT-User
Allow: /

User-agent: Claude-SearchBot
Allow: /

User-agent: Claude-User
Allow: /

User-agent: PerplexityBot
Allow: /

# 訓練型 AI 爬蟲：擋下（吃資料不回引）
User-agent: GPTBot
Disallow: /

User-agent: ClaudeBot
Disallow: /

User-agent: Google-Extended
Disallow: /

User-agent: CCBot
Disallow: /

User-agent: Bytespider
Disallow: /

# 內容信號：可被搜尋索引、不可訓練、不直接餵 AI 當輸入
Content-Signal: ai-train=no, search=yes, ai-input=no

robots.txt 的詳細寫法可以看我之前寫的 快速掌握 robots.txt 用途，整套 Agent Readiness 的滿分設定可以看 從 3 分到滿分！讓你的網站通過 isitagentready AI Agent Readiness 完整攻略。

這對寫文章有什麼具體影響？

那講完了這些東西，所以這件事情對於寫文章有什麼具體影響呢？答案是有的，你只要理解上面的限制跟細節之後，寫文章就可以針對這四件事情多下功夫。

標題要能獨立成立

搜尋階段 AI 看到你的文章，就只有 title 跟 URL 兩個欄位。

如果你的標題需要副標 or 上下文才看得懂，AI 把它跟其他十幾筆結果排在一起時就會被略過。

舉個對照：

• 比較弱的標題：「實作筆記」
• 比較強的標題：「Cloudflare Worker 把 HTML 轉 Markdown 的內容協商完整實作筆記」

後者把「主題、工具、做什麼事、文章類型」都塞進去了，AI 不用點開頁面就知道值不值得撈。

首段就直接給答案

WebFetch 階段，中介的 Haiku 模型是從上往下讀的，前 300 到 500 字決定它摘什麼回去。如果你的開頭是「在我們聊 X 之前，先來回顧一下歷史…」，Haiku 讀到一半發現都是背景沒答案，就直接摘背景了。

正確的寫法是每個 H2 段落開頭第一句話就直接給結論，後面再補脈絡。這個原則我在 SEO 已經不夠了嗎？認識 AEO 答案引擎優化 那篇也有提過，可以一起看。

設計可獨立引用的單句

cited_text 在 web_search 是 150 字元、Claude Code 內建 WebFetch 是 125 字元。這代表 AI 引用你的時候，能塞的就是一段「沒有上下文也能成立」的短句。

寫作的時候有意識地去設計這種句子，例如：

• 比較弱：「這個跟前面提到的那個方法不太一樣，主要差別在…」（沒有上下文看不懂）
• 比較強：「llms.txt 是 Answer.AI 共同創辦人 Jeremy Howard 在 2024 年提出的，目的是主動告訴 AI 網站有什麼重要內容。」（不需要前後文就成立）

寫完一段之後可以自己挑一句出來看，如果單獨拿出來給沒看過全文的人都看得懂，那這句就有機會被引用。

結構化內容當 Haiku 的航標

H2、H3、- 列表、表格、```js 程式碼區塊，這些 Markdown 結構對中介摘要層特別有用。Haiku 讀 HTML 轉出來的 Markdown 時，會把標題當「這段在講什麼」的索引，把列表當「主要要點」的訊號，把表格當「資料佐證」的單位。

如果你整篇文章都是純散文段落，Haiku 沒有航標只能靠語意硬讀，摘出來的東西就會偏散；如果你有清楚的結構，Haiku 摘的時候可以直接照航標走，得到的摘要會跟你想被引用的重點對齊。

結語

最後總結一下吧。

所以 AI 搜尋時，實際撈走你部落格多少呢？

我認為答案可以分成三層：

• 搜尋階段： 只有 title 加 URL
• 撈內文階段： API 預設裝得下你整篇，可是 Claude Code 走 Haiku 中介摘要 + 100 KB 截斷
• 引用階段： web_search 是 150 字元，Claude Code WebFetch 是 125 字元

寫文章針對的就是這三道閘門，不是讓 AI 把你整篇背起來。

希望這篇有讓你對 AI 搜尋實際撈走多少內容這件事有更具體的概念哩～

如果你的部落格還沒做 AI bot 分流，可以參考前面那段 robots.txt 範例先把基礎建設起來，剩下的就交給內容慢慢累積了。

前言

其實我對於 AI 生成一直抱持著問號的心態，畢竟手指、文字、聲音這些細節一直都是 AI 的罩門，生出來的東西常常看了會覺得「嗯…這是 AI 生的」，不太像真的拍出來的影片。

可是這陣子我自己實際用了一下，只能說…改善非常多，整體畫面滿厲害的，雖然有些小細節還沒到完美，可是已經到了「這是 AI 生的」跟「這是拍出來的」之間的模糊地帶了，尤其是我前陣子生成的

滿多朋友看了都嚇到，以為我真的親自拍了一個「Code Review 我的青春」的宣傳影片出來（ 不可能），所以我覺得 Gemini Omni 在「拍出來的」這件事上是有一定性的實質上的進步了。

如果你還不太熟 Prompt 結構、跟 LLM 怎麼互動，可以先去翻我之前寫的 你聽過 LLM、RAG、Prompt 嗎？一文帶你看懂生成式 AI 常見技術詞彙，這篇我就直接從 Gemini Omni 開始講。

那這一篇會分四大段：先釐清一個常見的混淆（Gemini App 裡的 Omni 跟開發者端的 Veo 3.1 不是同一個東西）、接著看 Omni 比 Veo 強在哪、再講提示詞怎麼寫才會穩，最後給你 30 個分場景的提示詞模板，IG Reels 鈎子、產品 Demo、Logo Reveal、Cinematic B-roll、Before-After 轉場、知識懶人包動畫、引言金句動態卡、Lifestyle 跟旅遊食物 cut 都有，可以直接複製去改。

先釐清：Gemini App 裡的影片是 Omni 還是 Veo？

很多人會問「那 Veo 跑去哪了？」，這個誤會其實滿正常的，因為 2026 年初的時候 Gemini App 裡面影片生成確實是 Veo 3.1 在跑，可是 5 月 I/O 之後整個換代了。

簡單來講就是：

• Gemini Omni 是 Google 在 2026 年 5 月 I/O 發布的全新統一多模態模型，現在是 Gemini App 裡影片生成的主力。一段 10 秒、9:16 或 16:9、原生帶同步音訊，可以混合文字 + 圖 + 影片 + 音訊一起當輸入。
• Veo 3.1 / Veo 3.1 Lite 並沒有消失，只是換崗位 — 它們被推到開發者端去了，現在主要透過 Gemini API、Vertex AI、Google AI Studio 提供，給工程師接 API 做產品或做大量批次生成用。

如果用比較生活面的例子來講，Gemini Omni 像是一台全自動相機，你跟它講想拍什麼它自己會調光圈快門；Veo 3.1 比較像是手動相機，控制力強但要自己會調。一般人在 Gemini App 上隨手生 Reels、生 IG 短片、做 Logo Reveal，Omni 就夠用了。

Gemini Omni 強在哪？

以我自己用下來，Omni 真正讓人有感的是這四件事：原生同步音訊、多模態混合輸入、中文文字渲染終於穩、對話式編輯。

一、原生同步音訊

過去 AI 影片最痛的不是畫面，是聲音。

畫面生出來還行，可是要配音、配 SFX、配環境音都得另外去 Pixabay 抓素材或進剪輯軟體加。

Omni 直接把這塊吞掉了，你只要在提示詞裡寫「對白：女主角說『我們得快點走了』」、「SFX：遠處雷聲」、「Ambient：午夜咖啡店的低語聲」，它會把這三層音訊跟畫面同步生出來，嘴型對得上、SFX 出現的時機也對（當然還是有些時候會稍微跑掉，可是已經很難辨別）。

二、多模態混合輸入

不只是文字描述。

你可以丟一張照片給它說「把這張照片動起來，咖啡冒煙、窗外有人走過」，它會以這張照片當第一幀往後延伸；也可以丟一段既有影片進去說「同樣的場景，改成黃昏光線」，它會做 style transfer。圖、音訊、影片、文字都能混著當輸入。

以我的範本來講，我就是將我書籍的封面給 Omni，然後他就將影片中書籍的封面直接替換成我給的圖，這樣就不用每次都在提示詞裡描述一次封面長什麼樣了，而且更準確。

三、中文文字渲染跟著補上來

這點跟前陣子 Images 2.0 把靜態圖的中文渲染解掉是同一條路線（如果你還沒看過 Images 2.0 在靜態圖上能做到什麼程度，可以順便看一下 GPT-5.5 跟 ChatGPT Images 2.0 怎麼用？30 個 IG 圖卡、知識卡、產品 Mockup 提示詞模板 那篇）。

Omni 把這套搬到動態畫面上，影片裡的中文字幕、開場標題、Logo 文字基本都寫得對，偶爾還是會跑掉一兩個字，可是已經到能用的程度。

四、對話式編輯

最有感的其實是這個。生完一段不滿意，你不用重寫整個 prompt，可以直接接著對話說「把光線改成黃昏的暖色就好，其他保留」，它會只動那塊。這對做系列內容（同主角、同風格、不同動作）很方便，不用每次都把所有細節重描一遍。

以我自己來講，這次的差別不在「畫得更藝術」，是在「畫得像真的拍出來的」。

剪輯後製（節奏、字卡、品牌色）還是要做，可是「拍攝」那段大概被 AI 吃掉八成（吧？）。

寫好影片提示詞的萬用結構

在你開始複製貼上模板之前，我們先聊一下影片 prompt 的整體結構，不然只是換主題複製貼上，產出穩定度會浮動很大。

以我自己參考了一輪官方指南再加上實際用下來，prompt 想穩，這六個面向都要描述到：

除了這六項，影片還有兩個靜態圖沒有的範疇，也就是「時間軸」跟「聲音」，這你必須要單獨講：

Note
兩件事不在 prompt 控制範圍：比例（16:9 / 9:16）是在 Gemini App 介面上選的、長度目前 Google 鎖死 10 秒（官方 說法是刻意設限不是模型限制）。
所以下面 30 個模板不會看到「請生一段幾秒的影片」這種句子，比例你依場景挑就好（人對鏡頭、Reels 風的就 9:16，cinematic、產品 Demo 就 16:9）。

簡單來講就是別讓模型自己猜，你猜得越具體它生得越精準。

如果你是要編輯既有的影片（局部修改而不是整段重生），那提示詞結構就要再加上「保留」跟「修改」的對比：

1
2

請保留：原片的人物、服裝、場景、構圖
請修改：把光線從正午改成黃昏的暖橘色、再加一段女聲說「就決定是這裡了」

這個結構的邏輯是「這段影片裡哪些元素是我要保留不動的、哪些元素是我要修改的」，這樣模型就不會把整段影片重生一遍，而是只動你說要修改的那部分，其他的保持原來的樣子。

30 個推薦提示詞模板

30 個提示詞依場景分成八類，全部中文、可以直接複製去改。

每一組我先講適用情境，再給 prompt 本體，後面接上我自己跑出來的成品，邊看邊對照，把 [ ] 裡面的內容換成你的主題就行。

Note
影片提示詞建議控制在 20 到 50 詞之間（或等長的中文），太短模型沒方向、太長重點會被稀釋。
而下面每個模板我都盡量壓在這個範圍。

一、IG Reels / TikTok 鈎子開場

這類短片就是你滑 Reels 的時候會被前 2 秒勾住停下來看的那種，重點是開頭立刻拋出衝突、提問或反差，不要花時間鋪陳。

1. 提問式鈎子（人對鏡頭講話）

最直接的開場，主角看著鏡頭問一句讓人想往下看的問題。

1
2
3
4
5
6
7

構圖：醫療診間風格的特寫，從正面看一位 25 歲的台灣女生坐在白色桌前、雙手抱胸、表情困惑。
風格：寫實、IG Reels 風、自然光感。
光線：柔和的窗光從左前方打進來。
場景：簡約白色背景、桌上一台筆電。
動作：她直視鏡頭、皺眉、嘆一口氣，然後說：『為什麼你的程式碼總是越改越亂？』
文字渲染：句子最後 1 秒在畫面底部用粗體中文字幕跳出『往下滑看答案 ↓』。
音訊：對白『為什麼你的程式碼總是越改越亂？』（清晰中文女聲）、Ambient 安靜辦公室微弱白噪音。

2. 第三人稱旁白鈎子

不出現真人臉，用手繪或符號特寫帶旁白，適合不想露臉的創作者。

1
2
3
4
5
6
7

構圖：俯視角度、特寫一支手在白紙上飛快寫程式碼。
風格：手繪動畫、停格動態。
光線：紙上方一盞暖黃檯燈。
場景：木桌、白紙、右上角一杯黑咖啡。
動作：手快速寫下『if、else、for、while』幾個關鍵字，最後畫一個大大的問號。
文字渲染：4 秒後在畫面上方浮現粗體標題『程式碼為什麼會亂？』。
音訊：鉛筆寫紙的沙沙聲、SFX 翻頁聲（最後一秒）、暖色 lo-fi 鋼琴背景音樂。

3. Before / After 兩秒切換開場

把對比直接濃縮在開頭兩三秒裡，視覺衝擊強。

1
2
3
4
5
6

[00:00-00:04] 構圖：特寫一個 90 年代的醜陋登入頁面（彩虹底色、Comic Sans 字體、跑馬燈標題），畫面有 CRT 螢幕掃描線質感。
[00:04-00:08] 構圖：同位置切換成現代極簡登入頁面（白底、襯線標題、清楚層級、淡藍 CTA 按鈕），畫面銳利乾淨。
風格：UI 設計教學、對比強烈。
動作：4 秒整時用 glitch transition 切換。
文字渲染：[00:00-00:04] 左上『2005』、[00:04-00:08] 左上『2026』。
音訊：[00:00-00:04] 老舊撥接 modem 撥號聲、[00:04-00:08] 現代清脆 UI tap 音效、SFX glitch 切換音。

4. 數字倒數開場

倒數天生就有「等等要發生什麼？」的拉力，適合榜單型內容。

1
2
3
4
5
6
7

構圖：純色背景中央放一個超大粗體數字，從 5 倒數到 1。
風格：極簡、海報感、現代感。
光線：扁平、單一光源。
場景：純黑背景。
動作：每秒切一個數字，倒數到 1 之後最後一秒切換成大字標題『2026 最該學的 5 個技能』。
文字渲染：數字使用霓虹紅、最後標題使用霓虹白；數字每次出現都有微微的 zoom in 動畫。
音訊：每秒一聲低沉鼓點、最後一秒換成清亮的鐘聲、SFX subtle whoosh。

5. POV 情境鈎子

第一人稱視角把觀眾帶進場景，沉浸感最強。

1
2
3
4
5
6
7

構圖：第一人稱 POV、看著自己的雙手在筆電鍵盤上打字。
風格：寫實 vlog 風、淺景深。
光線：晚間暖黃桌燈、後方有微弱藍色螢幕反光。
場景：木桌、一杯熱拿鐵、旁邊一本翻開的筆記本。
動作：手快速打字、然後停下來伸手拿馬克杯喝一口、放回去繼續打字。
文字渲染：3 秒時畫面上方浮現中文字幕『工程師的深夜 debug 日常』，停留 3 秒淡出。
音訊：機械鍵盤打字聲（青軸）、馬克杯放回桌面的悶響、Ambient 安靜的午夜窗外雨聲。

二、產品 / 服務 Demo

做行銷素材、做 Side Project landing page Hero、做產品介紹影片的時候，這類模板最常用。重點是介面要清楚、操作節奏要乾淨。

6. App 介面操作 Demo

把使用者最關鍵的一個操作流程濃縮在 8 秒內，適合做 IG 廣告或 App Store 預覽。

1
2
3
4
5
6
7

構圖：畫面中央一支 iPhone 微微傾斜 15 度，螢幕上是一款記帳 App 介面。
風格：科技產品 Demo、Apple Keynote 質感。
光線：柔和漸層背景光、手機螢幕有明顯反光高光。
場景：淺灰漸層背景。
動作：[00:00-00:03] 手指從下方滑入點擊『新增交易』按鈕、[00:03-00:06] 介面跳轉到記帳表單填寫畫面、[00:06-00:08] 顯示『已儲存』綠色成功提示。
文字渲染：App 名稱『MoneyTrack』固定在畫面右上角；介面內金額顯示『NT$ 320』。
音訊：UI tap 音效（清脆短促）、成功提示時的『叮』一聲、整段配輕快薄荷綠色調的 ambient electronica。

7. SaaS Landing Hero 動態背景

放在官網 Hero 區的動態背景，營造「這個產品很潮」的氣場。

1
2
3
4
5
6
7

構圖：寬廣 Hero banner 構圖，左側 60% 是大標題文字、右側 40% 是一台 MacBook 漂浮在空中，螢幕上滾動著儀表板資料。
風格：現代 SaaS Hero、未來感、漸層霓虹。
光線：紫藍漸層背景、MacBook 螢幕散發白光。
場景：純漸層背景，無多餘物件。
動作：MacBook 從畫面右側緩慢飄入、儀表板的資料數字持續向上跳動。
文字渲染：左側固定大標題『Ship faster with Insight』（白色粗體無襯線）、副標『Built for product teams』。
音訊：低沉電子合成器墊底、subtle UI 跳動聲、最後一秒淡入一聲 swoosh。

8. 商品 Mockup Loop（360 度旋轉）

電商商品頁、IG 商品 Reels 必備款，這種要做成無縫 loop。

1
2
3
4
5
6
7

構圖：畫面中央一個牛皮紙袋裝的精品咖啡豆包裝，置中、平視角度。
風格：精品攝影、極簡、攝影棚質感。
光線：頂光主光加側面柔光、背景無陰影。
場景：純白攝影棚背景。
動作：咖啡豆包裝沿垂直中軸 360 度緩慢旋轉一圈，剛好 6 秒回到原位置（適合無縫 loop）。
文字渲染：包裝正面印著『URBAN BEAN / Ethiopia Yirgacheffe』，旋轉到背面時可看到成份標籤。
音訊：純環境白噪音（攝影棚靜謐感），不加 BGM。

9. 服務流程動畫（解說型）

把抽象的服務流程視覺化，適合放在官網「How it works」區塊。

1
2
3
4
5
6
7

構圖：扁平動畫 explainer 風格，畫面分成三個橫向欄位，每欄一個步驟。
風格：扁平向量動畫、企業 explainer。
光線：扁平無光影。
場景：淺灰背景。
動作：[00:00-00:03] 第一欄畫出『使用者點擊』、[00:03-00:05] 第二欄畫出『系統處理』、[00:05-00:08] 第三欄畫出『回傳結果』，每欄之間有箭頭從左往右流動。
文字渲染：每欄底下分別寫『01 點擊』、『02 處理』、『03 回傳』。
音訊：每個步驟出現時配輕脆的『叮』、最後一聲較長的『叮〜』、背景輕快的 marimba BGM。

三、Logo Reveal / 品牌動態

放在影片開頭或片尾的品牌動態，3 到 6 秒最剛好。重點是節奏要乾脆，不要拖。

10. 經典 Logo 浮現

最安全的版本，任何場合都能用。

1
2
3
4
5
6
7

構圖：純色背景中央，Logo 從一片光霧中淡入。
風格：極簡品牌動態、Apple 質感。
光線：背景由暗到亮、Logo 出現時有微微光暈。
場景：純黑背景漸變為深藍。
動作：Logo 從中央放大 1.1 倍再回到原大小、停留 1 秒。
文字渲染：Logo 用『RAY HSU』粗體無襯線白字、下方副標『Frontend Engineer』細字。
音訊：低頻電子音逐漸升起、最後一聲清脆的 chime。

11. 液態金屬 Logo Reveal

質感比較重的版本，適合精品品牌或科技公司。

1
2
3
4
5
6
7

構圖：畫面中央一團流動的液態金屬球體，慢慢形變成 Logo 形狀。
風格：3D CG、奢華、高反射質感。
光線：環境光多反射、Logo 表面像鏡子般映出周圍光點。
場景：暗灰漸層工作室背景。
動作：[00:00-00:03] 金屬球體緩慢蠕動形變、[00:03-00:06] 形變成 Logo 字樣並穩定停留。
文字渲染：Logo 為『LUMEN』粗襯線字、最後一秒下方淡入細字 slogan『Crafted in light』。
音訊：低頻嗡鳴持續、最後 chime 加 sub bass drop。

12. 手繪墨水 Logo

文青系、生活品牌或個人工作室適合的版本。

1
2
3
4
5
6
7

構圖：白紙特寫俯視角度、一支毛筆從右上方滑入。
風格：手繪、書法質感、Wabi-sabi 美學。
光線：自然側光、紙面有細微紋理。
場景：日式米白紙背景。
動作：毛筆從右上方移動到中央、寫下兩個漢字 Logo、寫完後毛筆離開畫面、字停留 2 秒。
文字渲染：毛筆寫下『靜流』兩個漢字，行書風格。
音訊：毛筆沾水聲、毛筆筆觸沙沙聲、最後一秒淡入古箏單音。

四、Cinematic B-roll

B-roll 就是用來鋪在主畫面底下、墊節奏的素材。Omni 在這塊很強，因為它認得攝影語言，你寫 anamorphic、dolly forward、shallow depth of field 它都聽得懂。

13. 城市夜景 Drone shot

放在 vlog 開頭或封面預覽很有故事感。

1
2
3
4
5
6
7

構圖：空拍機高空俯視鏡頭、緩慢往前推。
風格：cinematic、Blade Runner 質感、anamorphic lens（畫面有 lens flare）。
光線：霓虹紫藍光、雨後街道有水反光。
場景：未來感的東京涉谷夜景、高樓林立、街上人潮流動。
動作：空拍機保持高度緩慢 dolly forward、車燈在街上形成光軌。
文字渲染：無。
音訊：cinematic ambient（synth pad）、遠處微弱的城市車流聲。

14. 慢動作雨滴特寫

療癒系內容、ASMR、保養品廣告很常見的鏡頭。

1
2
3
4
5
6
7

構圖：超特寫鏡頭對著一片綠葉、水滴從上方落下打在葉面。
風格：自然紀錄片、macro lens。
光線：清晨柔和側光、水珠有 specular highlight。
場景：森林綠葉、背景虛化的綠色 bokeh。
動作：水滴以慢動作（240fps 質感）落下、撞擊葉面後噴濺。
文字渲染：無。
音訊：水滴撞擊的低沉 boom（慢動作音效）、森林 ambient 鳥鳴。

15. 咖啡沖煮過程

生活感 B-roll 的萬用款，咖啡店、品牌廣告、文青 vlog 都能用。

1
2
3
4
5
6
7

構圖：手沖咖啡特寫、從上方 45 度俯視看著熱水從鵝頸壺倒進濾杯。
風格：質感攝影、咖啡品牌廣告風。
光線：早晨側窗光、蒸氣有逆光透明感。
場景：木桌、白色濾杯、底下黑色玻璃壺。
動作：水流穩定地畫圓注入濾杯、咖啡粉膨脹、蒸氣裊裊上升。
文字渲染：8 秒最後 1 秒畫面右下淡入小字『Slow brew. Slower mornings.』。
音訊：水流注入聲、咖啡萃取的細微氣泡聲、Ambient 安靜的早晨。

16. Time-lapse 城市黃昏

縮時很適合用 Omni 跑，因為它能直接生「光線變化」這種有時間軸的素材。

1
2
3
4
5
6
7

構圖：固定鏡頭、台北 101 為主視覺、前景有大樓剪影。
風格：time-lapse、cinematic、暖色調。
光線：從金黃 magic hour 過渡到深藍 blue hour 再到夜景燈火。
場景：台北信義區夜景。
動作：天空雲層加速流動、太陽落下、城市燈光逐一亮起。
文字渲染：無。
音訊：cinematic 漸進弦樂 swell、隨夜色加深音樂層次也加厚。

五、知識懶人包動畫版

之前在 IG 上做圖卡的人應該都很熟「知識懶人包」這個格式，把它動畫化之後互動率通常會再上一階。

17. 概念卡片翻轉

把名詞解釋濃縮成「正面題目、背面答案」的翻牌動畫。

1
2
3
4
5
6
7

構圖：畫面中央一張卡片，正反兩面分別寫『API』跟『程式之間的對話橋樑』。
風格：扁平向量動畫、IG 知識卡風。
光線：扁平柔和光影。
場景：米白底色、簡約。
動作：[00:00-00:02] 卡片正面『API』停留、[00:02-00:04] 卡片以 Y 軸翻轉、[00:04-00:08] 卡片背面『程式之間的對話橋樑』停留、底下浮現三個圖示（前端、API、後端）連成一條線。
文字渲染：卡片正面『API』、背面『程式之間的對話橋樑』。
音訊：卡片翻轉時的『刷』聲、最後三個圖示出現時各配一聲『叮』。

18. 三步驟流程動畫

把「該怎麼做」步驟化的動態版本。

1
2
3
4
5
6
7

構圖：畫面中央由上到下三個圓形節點，依序由箭頭連接。
風格：扁平動畫、教學風。
光線：扁平。
場景：純白背景。
動作：[00:00-00:03] 第一個節點放大、文字『01 切到分支』淡入、[00:03-00:06] 第二個節點放大、文字『02 git rebase main』淡入、[00:06-00:08] 第三個節點放大、文字『03 解衝突後 continue』淡入。
文字渲染：頂部固定標題『Git Rebase 三步驟』、三個步驟文字。
音訊：每個節點出現時配輕脆『噠』聲、背景輕快 marimba BGM。

19. 對比表動態揭曉

兩個東西並排比，逐項揭曉的版本，比靜態圖更能撐住觀眾的注意力。

1
2
3
4
5
6
7

構圖：畫面左右分欄、左 Vue 右 React，各列三個比較項目。
風格：扁平動畫、設計感。
光線：扁平。
場景：左欄淺綠底、右欄淺藍底。
動作：[00:00-00:02] 兩欄頂部 Logo 區塊淡入、[00:02-00:04] 三個比較項目由上而下逐項浮現、[00:04-00:06] 最後一項出現時兩欄底部都浮現一個對勾，意思是『各有強項』。
文字渲染：左欄頂部『Vue』、右欄頂部『React』、三個比較項『學習曲線』、『社群規模』、『生態系』。
音訊：每項出現時配輕脆音效、最後對勾出現時一聲較柔的『叮〜』。

六、Before / After 對比轉場

對比型內容在 Reels 上的觸及通常都很好，人類對「變化」這件事很有興趣。

20. 房間改造 Before / After

居家、收納、爆改類內容的招牌格式。

1
2
3
4
5
6
7

構圖：固定機位、拍攝同一個房間角落。
風格：寫實、IG 居家風。
光線：自然窗光。
場景：一間房間的書桌角落。
動作：[00:00-00:03] Before 狀態：桌面凌亂、電線雜亂、雜物堆積、整體灰塵感、[00:03-00:06] 用 wipe transition 從左往右過渡到 After 狀態：桌面整齊、線材收納、植物擺飾、明亮乾淨。
文字渲染：[00:00-00:03] 左上『Before』紅色標籤、[00:03-00:06] 左上『After』綠色標籤。
音訊：[00:00-00:03] 沉悶低頻、[00:03-00:06] 清脆鈴聲後接輕快 BGM、SFX wipe transition 音效。

21. Code 重構前後

工程師受眾很吃這套，把抽象的重構成果視覺化。

1
2
3
4
5
6
7

構圖：左右分割畫面、各顯示一段程式碼。
風格：終端機質感、深色主題、語法高亮。
光線：螢幕自發光。
場景：純黑背景。
動作：[00:00-00:03] 左側顯示 30 行雜亂程式碼（深紅色波浪線）、[00:03-00:06] 右側陸續打字出簡潔的 10 行版本（綠色 check mark）、最後左右兩側用 split screen 並列比較。
文字渲染：左上『Before：if-else 地獄』、右上『After：early return』。
音訊：機械鍵盤打字聲（密集）、最後一聲『check』音效。

22. 文案改寫前後

寫文案、做 copywriting 教學的人很愛用。

1
2
3
4
5
6
7

構圖：純色背景、中央一段文字。
風格：極簡、編輯設計感。
光線：扁平。
場景：奶油黃背景。
動作：[00:00-00:03] 顯示一段冗長文案（約 30 字）、底下小字『Before』紅色標籤、[00:03-00:06] 文字逐字消失重新打出精簡 8 字標語、底下小字『After』綠色標籤。
文字渲染：Before 段『我們提供業界最高品質的客製化網頁設計服務，從零到上線一條龍』、After 段『讓你的網站，被看見』。
音訊：文字消失時的『沙沙』聲、新文字打字機聲、最後一聲『叮』。

七、引言金句動態卡

把金句卡動態化，比靜態圖在動態牆上更容易停留。

23. 名人金句動態

設計、產品、領導力類的引言常常會被分享。

Note
Gemini Omni 對真實知名公眾人物的肖像跟名字會直接擋（政治人物、科技創辦人、藝人、運動員都一樣，Veo / Sora / Midjourney 那些主流工具也是這樣，這是平台對真人肖像濫用的內容政策）。要做引言或致敬類的內容就用虛構名字、匿名、或自己當作者，下面範例我就直接用自己當署名。

1
2
3
4
5
6
7

構圖：左側 1/3 是低飽和度的人物剪影、右側 2/3 是引言文字。
風格：編輯設計感、雜誌風。
光線：暖灰背景、單色剪影。
場景：奶油色背景。
動作：[00:00-00:02] 剪影淡入、[00:02-00:05] 引言逐字打出、[00:05-00:06] 署名行淡入。
文字渲染：主引言『Design is how it works.』、署名『— Ray』。
音訊：背景輕柔的 piano ambient、文字出現時的『沙沙』筆觸音效。

24. 中文短句金句

日系極簡風、IG 收藏型內容。

1
2
3
4
5
6
7

構圖：純色背景中央一句中文短文。
風格：日系極簡、文青風。
光線：扁平。
場景：奶油黃底色。
動作：[00:00-00:02] 文字由模糊到清晰浮現、[00:02-00:04] 停留 2 秒。
文字渲染：主句『慢慢來，比較快。』（手寫感中文字體）、右下角小字『2026.06 / @israynotarray』。
音訊：純環境的微弱 ambient，不加 BGM。

25. Story 翻頁式金句

連續放兩三句，模擬翻書節奏，適合 IG Story 廣告或品牌敘事。

1
2
3
4
5
6
7

構圖：模仿翻書效果、連續顯示三句格言。
風格：手繪本書質感、復古紙張紋理。
光線：暖光、紙張有微微陰影。
場景：木桌背景、紙張置中。
動作：[00:00-00:03] 第一句『起步前，先想清楚為什麼。』、[00:03-00:05] 翻頁、[00:05-00:08] 第二句『動手後，別停下來修正方向。』。
文字渲染：兩句中文用襯線字體。
音訊：翻頁的紙張聲、背景暖色木吉他和弦。

八、Lifestyle / 旅遊 / 食物 cut

這類是 IG Reels、TikTok 觸及最穩的內容類型，重點是節奏感跟氛圍。Omni 的 ambient 音訊在這邊很加分。

26. 早晨儀式 vlog cut

居家、生活感 vlog 的開場款。

1
2
3
4
5
6
7

構圖：手持攝影機抖動感、第一人稱視角。
風格：vlog、IG 系生活感、自然色調。
光線：清晨自然窗光。
場景：木質地板、白色床、窗邊綠植。
動作：[00:00-00:03] 鏡頭從床上的羽絨被慢慢移動到窗邊、[00:03-00:06] 拉開窗簾、晨光灑進室內、[00:06-00:08] 鏡頭轉到桌上的一杯熱拿鐵特寫。
文字渲染：8 秒最後 1 秒右下淡入小字『Slow morning, Saturday.』。
音訊：鳥鳴聲、窗外微弱車流聲、咖啡杯放下時的悶響、暖色 lo-fi 鋼琴 BGM。

27. 食物擺盤特寫

食譜、餐廳廣告、美食 IG 帳號必備。

1
2
3
4
5
6
7

構圖：俯視角度、一盤剛上桌的義大利麵特寫。
風格：食譜雜誌、暖色調。
光線：餐廳柔光、有微微背光透出熱氣。
場景：木桌、白色陶瓷盤、旁邊一杯紅酒。
動作：[00:00-00:02] 義大利麵剛上桌、熱氣裊裊上升、[00:02-00:04] 一隻手從右邊伸入撒上起司粉、[00:04-00:06] 鏡頭微微推近特寫蒸氣。
文字渲染：無。
音訊：起司粉撒落聲、餐廳遠處輕微背景人聲、暖色義式手風琴 BGM。

28. 旅遊一日 cut

多個快速 cut 組成的一日剪輯，旅遊帳號的常駐格式。

1
2
3
4
5
6
7

構圖：每個 cut 約 1.5 秒、總共 5 到 6 個地點。
風格：旅遊 vlog、IG Reels 剪輯感。
光線：根據時間變化（早午晚）。
場景：台北中山站一日散步行程。
動作：[00:00-00:02] 捷運站口 / [00:02-00:03] 文青咖啡店外觀 / [00:03-00:05] 街角文具店 / [00:05-00:06] 公園長椅 / [00:06-00:08] 夜晚霓虹巷子。
文字渲染：每個 cut 左下角浮現地點小字（『10:00 中山站』、『11:30 鳴草咖啡』等）。
音訊：節奏感強的 indie pop BGM、cut 之間有 swoosh transition。

29. 寵物日常特寫

療癒系內容，貓狗帳號的萬用素材。

1
2
3
4
5
6
7

構圖：低角度、貼近寵物視線高度。
風格：寵物 vlog、療癒系。
光線：午後柔光。
場景：木質地板、一隻橘貓躺在陽光斑點裡。
動作：[00:00-00:03] 橘貓懶懶地翻身、伸懶腰、[00:03-00:06] 鏡頭推近到貓臉特寫、貓打了個哈欠。
文字渲染：6 秒最後 1 秒右下角小字『Today's mood.』。
音訊：貓打哈欠的微弱聲音、Ambient 安靜午後、極輕的鋼琴單音。

30. 城市散步 walk-and-talk

訪談、紀錄片、podcast 預告片很常用的鏡頭語言。

1
2
3
4
5
6
7

構圖：跟拍鏡頭（gimbal）、從後方拍主角邊走邊講話。
風格：紀錄片風、自然光、新聞訪談感。
光線：黃昏側光、長影子。
場景：台北舊街區、紅磚老房、騎樓。
動作：主角從畫面右側慢步往前走、邊走邊回頭對鏡頭講話、相機保持穩定跟拍。
文字渲染：開頭 2 秒右下角浮現姓名字幕『阿明 / 文字工作者』。
音訊：主角對白『我覺得這條街有種台北 90 年代的味道』（清晰中文男聲、台灣口音）、Ambient 街角機車聲、遠處狗叫。

實際使用的小技巧

光知道結構跟模板還不夠，這邊補幾個我自己用下來覺得有用的小技巧。

一、中文出包怎麼救（字幕、口音都算）

字幕跑掉一兩個字的話，不要整段重生，直接在 Gemini App 的對話框接著說…

1

請只把 02 秒的字幕『XXX』改成『YYY』，其他保留。

那它就只動那塊。

如果整段字幕都跑掉，那大概率就是提示詞沒有用引號明確標出文字，回去把字用 「」、『』 包起來再生一次就會穩定很多。

至於…口音的部分，中文對白偶爾會跑成非預期的腔調、或是英文味很重的中文，這時候只要在提示詞裡加「清晰的台灣口音中文女聲」或「自然的台灣男聲」這種明確標註，準確率會明顯提高。

二、想做無縫 loop 影片的話

商品 Mockup、Logo 背景、SaaS Hero 這種要不停循環的素材，提示詞裡要明確寫「可循環播放」、「第 0 秒跟第 N 秒的畫面要對齊」，然後動作要設計成週期性的（旋轉一圈、循環移動等），不要寫「咖啡杯被打翻」這種一次性的動作。

三、構圖比例對應平台

不同平台的影片比例不一樣，記得在 Gemini App 介面上生成前先把比例切好（目前只有 16:9 跟 9:16 兩種，其他比例要事後裁切），不然產出可能不能直接用。常見比例整理在下面：

從這張表可以看出來，現在的影片內容大宗已經是 9:16 直式，要做 Reels 就在 App 上先切 9:16，要做 YouTube 主影片再切 16:9，不要兩邊都用 16:9 然後直式裁切，那樣畫面比例會跑掉。

四、不要一鏡塞太多動作

我只能說 10 秒能講的東西其實很有限。

如果你的提示詞同時要求「主角走進門 + 坐下 + 打開筆電 + 開始打字 + 喝一口咖啡」，那模型絕對塞不完，最後通常會犧牲掉動作流暢度跟物件一致性。

建議一段影片最多 1 到 2 個主要動作，要多就用 timestamp 拆成多鏡頭，或者乾脆拆成兩段分別生，再剪在一起。

結語

整理到這邊，這篇文章把 Gemini Omni 跟 Veo 3.1 在 Gemini App 端的分工、Omni 強在哪、提示詞結構、30 個分場景的提示詞模板都收錄進來了。

說真的，AI 影片在 Omni 之前我都覺得它是玩具，做做個概念 demo、做生成式藝術很適合，可是要拿來剪 Reels、做產品 Demo、做 Logo Reveal，總是差那一口氣，不是動作會卡、就是文字會糊、不然就是要再去找配樂跟音效。

Omni 是第一次讓我覺得「這真的可以直接拿來剪」（應該吧）。

當然 AI 影片還是有它的極限，需要精準品牌規範或長秒數敘事的素材還是要回到真人攝影 + 剪輯，可是日常 80% 的短片素材，你完全可以靠這 30 個模板自己生哩～

如果你想把 Gemini 變成自己的影片生成小幫手，可以順便看一下 Gemini Gems 教學：輕鬆打造你的專屬 AI 助手，把這套提示詞結構打包成一個專屬的 Gems，下次就不用每次都複製貼上整段了。

當然這邊如果懶的話，你也可以直接參考一下我之前做的 Awesome Gemini Gems，裡面有許多我準備好的 Gems，未來我可能也會增加一些影片生成相關的 Gems，歡迎隨時來逛逛～

希望這 30 個模板對你的內容創作有實際幫助哩～

反正跟其他文章一樣，只要你直接複製貼上就會發現產出不太一樣，畢竟 AI 生成每次都有隨機性（笑）

Note
Auto Memory 會將你的 feedback 儲存到 ~/.claude/projects/<專案>/memory/ 底下，雖然不會佔用 RAM，但它卻會佔用你的 Context Window 跟磁碟空間。好消息是記憶檔通常只有 KB 等級，真正讓 ~/.claude/projects/ 膨脹到幾百 MB 甚至 GB 的兇手其實是同一個資料夾底下的 conversation jsonl。Claude Code 預設會用 cleanupPeriodDays（30 天）自動清掉舊的 session 檔，但如果你最近剛好跑了一個超大的 session，等 30 天可能有點久，可以用 find 把大檔案揪出來處理。

前言

前陣子朋友突然私訊我：「ㄟ，Ray，我電腦突然硬碟少了整整 300~500 MB 的空間耶？而且每次啟動 Claude 馬上就少了很多 Context，你有頭緒嗎？」

其實我大概知道原因，因為朋友這陣子正好瘋狂在使用 Claude Code 開發，第一直覺我就幫他看了一下 ~/.claude/projects/，果不其然，這個資料夾已經佔用了 300 多 MB 的空間，而這個東西其實就是 Claude Code 的 Auto Memory 機制導致，所以這一篇就要來聊一下這一塊。

另外，之前我有寫過一篇 Claude Code Auto Memory 是什麼？自動記憶功能完整教學 介紹 Auto Memory 的基本概念跟運作方式，這一篇就接續那一篇，來聊一下 Auto Memory 到底「佔」了什麼、什麼東西才是真的在吃你的磁碟跟 Context Window，以及怎麼處理。

Auto Memory 到底佔用了什麼？

我們先來聊一下 Auto Memory 到底佔了什麼哪些資源，簡單來說就是兩個：

Note
這邊要特別提醒一下，我這邊寫的「記憶體」並不是 RAM，而是 Context Window 跟磁碟空間。

那怎麼找到這個 MEMORY.md 呢？它其實就是你專案資料夾底下 memory/ 的索引檔，路徑是 ~/.claude/projects/<專案>/memory/MEMORY.md，裡面會列出你所有的記憶檔（通常是一些 Markdown 檔），每一條是一個索引，Claude 會根據這個索引去讀對應的記憶內容。

Context Window：MEMORY.md 怎麼吃 token？

首先，Auto Memory 的記憶內容是以 Markdown 檔的形式存在磁碟上的，Claude Code 每次啟動對話的時候會自動把 MEMORY.md 裡面的內容載入到 Context Window 裡面，讓 Claude 在對話過程中可以參考這些記憶。

可是 MEMORY.md 並不是整份載入，而是有一個限制：

Auto Memory 只會載入 MEMORY.md 的前 200 行或前 25KB（取小的那個）到 Context Window 裡面。

也就是說，如果你的 MEMORY.md 超過 200 行或 25KB 的話，超過的部分根本不會被載入到 Context Window 裡面，這也是為什麼有些人使用 Claude 之後，發現自己明明曾經講過，Claude 它也說過它會記憶下來，但它實際上根本不記得了，因為它根本沒看到那些記憶。

這邊也來讓我們看一下實際的 MEMORY.md 內容會是長什麼樣子：

1
2
3

- [feedback_writing_style.md](./feedback_writing_style.md) - 不要在文案中大量使用「」和 emoji
- [feedback_pnpm.md](./feedback_pnpm.md) - 此專案使用 pnpm，不要用 npm
- [feedback_uiux_skill_for_ui_work.md](feedback_uiux_skill_for_ui_work.md) — 牽涉 UI／UX 的修改一律呼叫 `ui-ux-pro-max:ui-ux-pro-max`

其實每一條都是很單純的一句話索引，加上連結指向實際的記憶內容檔案，這樣的管理方式對於 Context Window 的佔用是非常友善的，而實際的細節只會在對話中需要的時候才會被 Claude 讀取，這樣就不會讓 Context Window 被大量細節佔滿，因此以前面講的 feedback_uiux_skill_for_ui_work.md 它就會像這樣：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

---
name: UI 相關修改必須透過 ui-ux-pro-max skill
description: 任何牽涉 UI／UX 的調整、修改、新增，都要用 Skill tool 呼叫 ui-ux-pro-max:ui-ux-pro-max
type: feedback
originSessionId: bd73d7ce-893d-423f-2344dd123dw
---
只要這次修改牽涉 **UI／UX**（畫面排版、互動行為、視覺呈現、元件設計、Tailwind class、元件結構等），**必須透過 Skill tool 呼叫 `ui-ux-pro-max:ui-ux-pro-max`** 進行，不要自己直接改。

**Why:** Ray 明確指示「只要跟 UI 扯到你都要呼叫 UIUX SKILL Pro 去調整跟修改或者新增」。交給專門的 skill 處理可確保一致性與品質。

**How to apply:**
- 評估這次修改是否牽涉 UI（任何 .vue 檔的 template / style 區塊、Tailwind class 變更、新元件、互動流程調整都算）
- 牽涉 UI → 呼叫 `Skill({ skill: 'ui-ux-pro-max:ui-ux-pro-max', args: '<簡述要改什麼' })`
- 不牽涉 UI（僅 .ts service／types／composable 邏輯）→ 可自行處理
- 邊界案例（例如 composable 影響 UI 行為但本身不是 UI）：以「最終會不會改到 .vue」為判斷基準
- 呼叫前先準備清楚的需求描述（要改哪個畫面、目前的問題、期望的方向），這個 skill 才能產出有用的建議

這邊你會看 name、description、type、originSessionId 這些 metadata，其實你會發現跟 SKILL 的格式很像，你可以把 Auto Memory 看成一個另一種特殊的 Skill，Claude 會根據這些 metadata 來判斷這條記憶是什麼類型、來自哪個 session，以及它的內容是什麼，因此 description 的描述是非常重要的。

如果你發現你的 Claude Code 總是沒辦法正確讀取你要求的記憶內容，那很可能就是因為 description 寫得不夠清楚，Claude 看不懂它是什麼東西，自然就不會去讀取它了。

怎麼讓 MEMORY.md 瘦下來？

如果你發現 MEMORY.md 已經膨脹到接近 200 行，有幾個方式可以瘦身：

1. 把細節拆到 Topic 檔案：MEMORY.md 只留索引，每條一行帶連結就好，實際內容寫在獨立的 .md，Claude 需要時會自己去讀
2. 刪掉過時的記憶：直接在對話中跟 Claude 講「忘記之前關於 X 的規則」，or 自己手動到 ~/.claude/projects/<專案>/memory/ 底下刪掉對應檔案
3. 手動編輯 MEMORY.md：它就是普通的 Markdown，自己用編輯器打開整理就好

Note
通常大多都是請 AI 整理，而不是自己動手，畢竟 Auto Memory 的重點就是讓 AI 來幫你管理這些記憶內容，自己動手就失去意義了？但理解一下這一塊的結構跟運作方式，對於後續的使用跟排除障礙還是很有幫助。

磁碟空間：真正膨脹的兇手不是 Auto Memory

接下來是磁碟這一塊，這也是大部分人會誤解 Auto Memory 的地方。

我們先看 Auto Memory 本身佔多少。以我自己的專案為例，記憶資料夾長這樣：

1
2

du -sh ~/.claude/projects/-Users-rayxu/memory/
# 52K

整個 memory/ 加起來才 52KB，這個大小基本上你一輩子都用不完。

那…一整個 projects 資料夾呢？

1
2

du -sh ~/.claude/projects/
# 339M

意外吧？竟然高達 339 MB！所以真正佔用的人到底是誰哩？

答案就是 conversation jsonl — Claude Code 把你的每一次對話都存成一個 .jsonl 檔，每一行是一個 JSON 物件，包含你的 prompt、Claude 的回應、工具呼叫、工具結果，全部寫下來。長對話跟有大量檔案讀寫的 session，單一檔案就可能 MB 等級。

實際看一下：

1
2
3
4
5
6

ls -lh ~/.claude/projects/*/*.jsonl | sort -k5 -h | tail -5
# 5.7M  -....jsonl
# 5.9M  -....jsonl
# 6.2M  -....jsonl
# 6.2M  -....jsonl
# 8.1M  -....jsonl

可以看到最大的單一對話檔已經到 8 MB 了。

所以下次你看到 ~/.claude/projects/ 一直膨脹，先別怪 Auto Memory，去 du 一下就會發現真正的兇手是這些 .jsonl。

所以該怎麼自動清理？認識 cleanupPeriodDays

ok，其實有一個方式可以解決這件事情，本身 Claude Code 就有內建一個自動清理機制，預設就會把超過 30 天的 session 檔在啟動時自動刪掉，這個設定叫做 cleanupPeriodDays。

Note
cleanupPeriodDays 只會清 conversation 紀錄，不會動到 Auto Memory 的記憶檔。你之前寫的記憶都不會被它刪掉，可以放心。

如果你想改保留天數，在 ~/.claude/settings.json 加上這條：

1
2
3

{
  "cleanupPeriodDays": 7
}

這樣 Claude Code 每次啟動時就會把超過 7 天的 jsonl 都清掉（最少可以設 1 天，設 0 會出現錯誤哦）。

那如果你完全不想保留任何對話紀錄（隱私考量 or 純粹想省空間），可以直接停用 transcript 寫入：

1

export CLAUDE_CODE_SKIP_PROMPT_HISTORY=1

把這行加到你的 ~/.zshrc 或 ~/.bashrc，從此 Claude Code 就不會再寫 conversation jsonl 了。代價是你也不能再用 claude --resume 回到之前的對話，魚與熊掌就看你怎麼選擇了。

手動清理大檔案

雖然 cleanupPeriodDays 會自動清理，可是如果你最近兩週剛好跑了一個超大的 session（例如連續開 subagent 解 bug），等 30 天有點久。

這時候可以用 find 把大檔案揪出來：

1

find ~/.claude/projects -name "*.jsonl" -size +50M -exec ls -lh {} \;

這條指令會找出 ~/.claude/projects/ 底下所有超過 50 MB 的 jsonl 檔。確認過內容你不需要保留之後，再用 -delete 把它們刪掉：

1

find ~/.claude/projects -name "*.jsonl" -size +50M -delete

Note
刪掉某個 session 的 jsonl 之後，那個 session 就無法用 claude --resume 救回來了。如果你還想保留近期的對話紀錄，刪之前最好先 ls -lh 確認一下檔案的修改時間，挑你真的不會再回頭看的那幾個就好。

順便看哪些專案資料夾最肥

~/.claude/projects/ 底下每個資料夾對應一個你曾經用 Claude Code 開啟的目錄，可是專案如果你早就不維護了，那它對應的資料夾也沒必要留。可以這樣看哪些資料夾最肥：

1

du -sh ~/.claude/projects/*/ | sort -h | tail -10

確認哪幾個專案是你已經不會再 resume 的，整個資料夾直接刪掉就好。

那資料夾底下還有別的東西嗎？

除了 conversation jsonl 跟 memory/ 之外，每個專案資料夾底下還可能有一些以 UUID 命名的子資料夾（沒有 .jsonl 副檔名的純資料夾），那些是 subagent 跑任務時用的暫存空間。一般來講不需要動它們，cleanupPeriodDays 也會一起清。

如果你有用 Worktree 跑 subagent，舊的 worktree 也會在啟動時被自動清掉，同樣由 cleanupPeriodDays 控制。

希望這篇有讓你對 Auto Memory 的「佔用」有更近一步的認識哩～

下次磁碟爆滿的時候，記得先 du 看一眼是哪邊真的在吃，不要冤枉了 Auto Memory。

Note
Claude Code Hooks 是 Claude Code 生命週期裡的「自動觸發點」，會在你期望的時候自動觸發你寫的 Shell 指令。而常用的生命週期有 PreToolUse（工具執行前）、PostToolUse（工具執行後）、UserPromptSubmit（每次送 prompt 前）、SessionStart（session 開啟時）。你需要將相關設定寫在 settings.json 的 hooks 區塊就可以了。

前言

用 Claude Code 開發一段時間後，你應該有遇過類似的狀況，也就是每次叫它改完檔案還要再請它跑一次 Prettier 跟 ESLint（當然也可以手動自己執行 npm run format），但人總是會偷懶，想要在比較放飛的時候開個 --dangerously-skip-permissions，但開了又會怕它跑了 rm -rf 之類的指令；又或者 Context 被 Compact 之後，它就忘了專案的某些重要約定，又要重新講一次 QQ…

所以這篇就要來介紹與分享一下 Claude Code 中很重要的技巧，也就是 Hooks，讓你可以在 Claude Code 的生命週期裡「掛鉤」你想要的自動化動作，確保它在對的時間點幫你做對的事。

另外，之前我有寫過 Claude Code 哪些檔案該 Commit？CLAUDE.md、Settings、Rules、Skills 完整解析，裡面有大致提到 .claude/settings.json 的層級概念，這篇就接續那一篇，把 hooks 這個藏在 settings 裡面的進階功能拉出來獨立詳細介紹一下。

Hook 跟 Skill、CLAUDE.md、Rules 差在哪？

在開始講 hook 怎麼設之前，先讓我們快速回顧一ㄒ它跟其他「教 Claude 做事」的機制差別，這樣會比較清楚彼此之間到底在幹嘛。

如果上面表格看完還是很難懂的話，那你可以這樣理解

1. CLAUDE.md 跟 Rules 是「規則」
2. Skill 是「能力」，這三個都是 Claude 自己看完之後再決定要不要照做。
3. Hook 不一樣，hook 是 Claude Code 本體幫你執行的，Claude 沒有選擇權，到了那個時機就一定會執行的事情。

這邊也簡單舉一個例子，假設你在 CLAUDE.md 裡面寫「每次改完檔案請跑 Prettier」，Claude 大部分時候會聽，可是偶爾會忘記（畢竟 Context 可能爆掉了？！），如果你改用 PostToolUse hook 設定「每次 Edit 或 Write 之後自動跑 Prettier」，那不管 Claude 想不想跑，反正你的 Shell 指令一定會被執行。

所以 hook 適合的的場景是…

我絕對不能容忍 Claude 漏掉的事

像是 lint、format、安全防護這些，而比較模糊、需要 Claude 判斷的事還是寫在 CLAUDE.md 比較合適。

Hook 的設定檔長什麼樣子？

Hook 的設定都是寫在 settings.json 的 hooks 區塊裡面，而它的結構是長這樣：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "事件名稱": [
      {
        "matcher": "篩選條件",
        "hooks": [
          {
            "type": "command",
            "command": "你要跑的 Shell 指令"
          }
        ]
      }
    ]
  }
}

外層的 key 是「事件名稱」（例如 PreToolUse、PostToolUse），裡面包一個陣列，陣列每一項是一組設定，包含 matcher（用來過濾這組要在什麼狀況下啟動）跟 hooks（實際要跑的指令）。

如果你之前看過 Claude Code Status Line 設定教學，會覺得這個結構滿熟悉的，因為它跟 Status Line 一樣都是「Claude Code 餵資料給你的 Shell，你決定怎麼回應」。

設定檔放在哪？

跟其他 Claude Code 設定一樣，hooks 也有層級分別：

簡單來講，全團隊都應該裝的 hook（例如 lint）寫在 .claude/settings.json、個人偏好（例如桌面通知）寫在 ~/.claude/settings.json、跟敏感路徑相關的本機規則寫在 .claude/settings.local.json。

Hook 事件有哪些？

聊完設定檔的結構，接下來就是這篇的重頭戲，也就是「到底有哪些事件可以使用？」

老實講，Claude Code 提供的事件超過 20 個，全部寫出來會把人嚇跑，所以這邊我以我自己「實務上會用到的頻率」分類列給你看。

下面這張圖是 Claude Code 一輪典型 session 的生命週期，每個箭頭上面標的就是會觸發的事件，可以對照看 hook 大概在哪個位子會被呼叫：

最常用的幾個

這六個算是屬於最常被用到的事件，許多實戰範例都會繞著它們轉。

其他比較少用但值得知道的

看到現在為止，應該可以知道 hook 幾乎涵蓋了 Claude Code 跑起來會經過的所有節點，幾乎你想得到的「我希望某件事發生時自動跑某個指令」都做得到，概念就跟寫成是的「生命週期事件」一樣。

matcher 怎麼寫？

接下來我們總要來介紹一下該怎麼撰寫 hook 的條件了。

前面有看到 hook 範例是長這樣：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "事件名稱": [
      {
        "matcher": "篩選條件",
        "hooks": [
          {
            "type": "command",
            "command": "你要跑的 Shell 指令"
          }
        ]
      }
    ]
  }
}

matcher 決定「這組 hook 在什麼狀況下要啟動」，而它要比對什麼東西會隨事件而不同。最常用的 PreToolUse / PostToolUse 比對的是「工具名稱」，所以最直覺的寫法就是把工具名直接丟進 matcher 欄位。

舉個實際的例子，下面這個 hook 是「Claude 每次要跑 Bash 之前，在終端機上顯示一段提醒」：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -n '{ systemMessage: \"Bash 要執行了\" }'"
          }
        ]
      }
    ]
  }
}

接下來畫面就可以看到 Bash 要執行了 的提醒了。

matcher 的值就是工具名 Bash，意思是「只在 Claude 用 Bash 工具時這個 hook 才會跑」。

Note
為什麼這邊要用 jq 不用 echo？因為 Claude Code 跟 hook 之間是用「JSON 格式」對話的，如果你直接寫 echo "Bash 要執行了"，Claude Code 收到的就只是一段沒結構的純文字，它看不懂你要它幹嘛，就只會把這段話當成 hook 的執行紀錄收掉（忽略），Claude 永遠看不到。而 jq -n '{ systemMessage: "Bash 要執行了" }' 是在產出一段 JSON，等於是跟 Claude Code 講「這個欄位叫 systemMessage，內容請你塞給 Claude 看」，Claude Code 看到這種它認得的格式，才會真的把訊息餵進去。

如果你想一次盯多個工具，中間用 | 隔開就好。例如下面這個 hook 是「Claude 每次用 Edit 或 Write 改完檔案，自動跑 Prettier」：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

看到這邊我知道 command 有點複雜，所以我來拆解解釋一下：

1. Claude 用 Edit / Write 改完檔案的當下，Claude Code 會把一段 JSON 丟給這個 hook，裡面大概長這樣 — { "tool_input": {"file_path": "/path/to/file.ts" }, ... }，告訴你它剛剛改了哪個檔。
2. 接著 jq -r '.tool_input.file_path' 就是把這段 JSON 拆開，從裡面挖出 tool_input.file_path 這個欄位的值（也就是檔案路徑），-r 的意思是「給我純文字就好，不要有雙引號」。
3. |（pipe）你就把它當作大隊接力的接力棒，意思是「把上一個指令的結果，當成下一個指令的輸入餵過去」。
4. xargs 負責把接過來的東西「接在下一個指令的後面當參數」，所以實際跑出來會變成 npx prettier --write /path/to/file.ts。
5. npx prettier --write 就是呼叫 Prettier 把這個檔案 format 一遍。

Note
prettier 是一款程式碼格式化工具，--write 是它的參數，意思是「直接改檔案」，如果你不想改檔只想看差異，可以換成 --check。如果你的專案不是用 Prettier 而是 ESLint，把 npx prettier --write 換成 npx eslint --fix 就好。

基本上，後面範例你只要看到 jq -r '.xxx' 就是再做這些事情，也就是：

jq -n 將 Claude Code 丟過來的 JSON 解析出來，抓你想要的欄位值，然後丟給下一個指令用。反之前面那個 jq -n 才是反過來「從零產生」一段 JSON 餵回去給 Claude Code。

最後，如果你想要「不管什麼工具都觸發」，那就把 matcher 留空字串：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_name' >> ~/.claude/all-tools.log"
          }
        ]
      }
    ]
  }
}

這個 hook 會在 Claude 用任何工具之前把工具名追加到 log 檔，等於是把整個 session 的工具使用紀錄起來。

到這邊 95% 的場景已經夠用了，要看每個工具叫什麼名字，可以參考之前我寫的 Claude Code 內建 Tools 在做什麼？看懂它怎麼選工具，裡面把每個工具的名字都列出來了。

進階：要篩 MCP 工具就要用 regex

剩下 5% 的情境就是當你要比對 MCP server 提供的工具時。MCP 工具的命名格式長這樣：mcp__<server>__<tool>，舉例來說 GitHub MCP server 提供的搜尋工具叫做 mcp__github__search_repositories。

如果你想一次盯某個 MCP server 提供的所有工具，可以用 regex 的 .* 配對任何字元：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'GitHub MCP tool called' >&2"
          }
        ]
      }
    ]
  }
}

.* 是 regex 的「任何字元」，所以 mcp__github__.* 的意思就是「mcp__github__ 開頭，後面接什麼都符合」。Claude Code 判斷要不要當 regex 的規則很單純：matcher 只要不只由「字母、數字、_、|」這四種組成，就會走 JavaScript regex 模式；反之就當完整字串比對。所以前面 Bash、Edit|Write 那種寫法不會被誤判成 regex。

不是所有事件都比工具名

前面講的都是跟工具有關的事件，可是有些事件 matcher 比對的不是工具名，而是「事件本身的某個分類」。

最常見的例子是 SessionStart，它比對的是「session 是怎麼開的」。下面這個 hook 是「Context 被 Compact 後 session 重建時，重新提醒 Claude 專案規則」：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo '提醒：套件管理用 pnpm 不要用 npm'"
          }
        ]
      }
    ]
  }
}

看到 echo '提醒：套件管理用 pnpm 不要用 npm'你應該會充滿疑問想著…

「前面你不是說 PreToolUse 的 echo 沒用嗎？怎麼這邊又這樣用？」

這是因為 SessionStart 跟 UserPromptSubmit 是兩個比較特殊的事件，hook 輸出到畫面的內容會被 Claude Code 自動當成「要塞給 Claude 的額外脈絡」收進去，所以直接 echo 就會被 Claude 看到。其他事件（像前面的 PreToolUse）才要走 jq -n '{systemMessage: ...}' 這種 JSON 格式跟 Claude Code 對話。

matcher: "compact" 限定「只在 Compact 後重建 session 時跑」，第一次開 Claude Code 或 resume 舊 session 都不會觸發。SessionStart 的可選值有 startup（第一次開）、resume（恢復舊 session）、clear（清空 context）、compact（壓縮後）。

Notification 也是類似邏輯，它比對的是「通知類型」，常見的有 permission_prompt（Claude 在等你授權）、idle_prompt（Claude 沒事在等下一句），另外還有 auth_success、elicitation_dialog、elicitation_complete、elicitation_response 等比較少用的。每個事件 matcher 對應什麼，可以查 官方 hooks reference，這邊就不一一列了。

進階：用 if 連工具參數也篩

光是 matcher 還不夠精確，因為它只能比對工具名。如果你想說「只在 Claude 跑 git push 的時候才觸發 hook，其他 Bash 指令不要管」，那你需要更細的 if 欄位：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git push *)",
            "command": "echo 'Blocked: 請走 PR 不要直接 push 到 main' >&2; exit 2"
          }
        ]
      }
    ]
  }
}

這個範例做的事情是：當 Claude 想跑任何 git push 開頭的 Bash 指令時，hook 就會輸出一段擋下的訊息然後 exit 2 把這個動作擋掉。可是如果 Claude 想跑的是 git status 或 npm test，hook 根本不會被叫起來。

兩個篩選欄位的差別是：

• matcher: "Bash" 是第一層粗篩，「只看 Bash 工具」。
• if: "Bash(git push *)" 是第二層細篩，連 Bash 裡面實際要跑的指令也比對，* 是「後面接什麼都行」的萬用字元，跟 permissions 設定用的是同一套語法。

它最大的好處是「只有真的命中條件時才會把 hook 跑起來」，比起每次都把 hook 叫起來再用 jq 解析參數判斷，效能差很多。

Note
if 欄位是後來才加的，比較舊版本的 Claude Code 可能不認得這個欄位，如果你寫了 if 但 hook 行為跟沒寫一樣，先用 claude --version 確認版本然後更新看看。

Hook 怎麼跟 Claude Code 溝通？

理解 matcher 之後，再來看 hook 跟 Claude Code 是「怎麼互傳訊息」的。先看一個最小範例：

1
2
3
4
5
6
7
8
9
10

#!/bin/bash

# 1. 將 Claude Code 丟過來的 JSON 儲存到 INPUT 變數裡
INPUT=$(cat)

# 2. 輸出一段訊息給 Claude Code 看，因此不會直接在終端機上看到，而是被 Claude Code 當成 hook 的回應收掉
echo "Claude 你好"

# 3. 結束 script，回傳 0 代表「沒事，繼續」，如果你寫 `exit 2` 就代表「有事，擋下這個動作」
exit 0

舉個 PreToolUse 的例子，當 Claude 要跑 npm test 時你的 hook 從 stdin 會收到這樣的 JSON：

1
2
3
4
5
6
7
8
9

{
  "session_id": "abc123",
  "cwd": "/Users/ray/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

Note
很多人寫 hook 第一次踩雷就在這邊：以為 exit 1 會擋，但只有 exit 2 才會擋，其他 non-zero 都不會。

用 JSON 回應做更細的控制

只能用 exit 0 跟 exit 2 嗎？不對，還可以做更細的控制（例如自動同意 or 直接改寫 Claude 想跑的指令），方法是 exit 0 然後輸出一段 JSON 到 stdout：

1
2
3
4
5
6
7

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "請改用 pnpm 不要用 npm"
  }
}

permissionDecision 在 PreToolUse 有四個值：

• allow：跳過權限提示直接放行
• deny：擋下來並把理由餵給 Claude
• ask：照原本的權限流程跳出提示問你
• defer：hook 沒有意見，回到原本的權限流程（效果等同沒寫這個欄位）

Note
Exit 2 跟 JSON 不要混用，Claude Code 看到 exit 2 就會直接讀 stderr 當理由，stdout 的 JSON 會被忽略。要嘛 exit 2 配 stderr，要嘛 exit 0 配 JSON，選一邊就好。

五種 Hook Type

前面範例都是用 type: "command"，這是最常見的形式，可是 Claude Code 還有另外四種：

90% 的人寫 hook 都會停在 command，可是後面三種（特別是 prompt）滿值得認識的，因為它讓 hook 能做的事情從「死規則」變成「有判斷力的守門員」。

舉個 prompt hook 的例子，假設你想在 Claude 講完話之後，讓另一顆模型檢查它有沒有真的把任務做完：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "檢查剛剛 Claude 是否真的完成了所有要求的任務。如果沒有，回覆 {\"ok\": false, \"reason\": \"還缺什麼\"}。"
          }
        ]
      }
    ]
  }
}

這個 hook 觸發時 Claude Code 會自動呼叫一顆模型做單輪 yes/no 判斷，如果回覆判斷沒做完，主 Claude 就會繼續做下去，相當於免費幫你裝了一個品管站。

實戰範例

聊完概念接下來看實際範例。下面這些是我認為日常最常用到、CP 值最高的幾個。

自動 format 改過的檔

每次 Claude 用 Edit 或 Write 改完檔之後，自動跑 Prettier 把格式修好：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

這邊用 jq 把 stdin 餵進來的 JSON 解析出 file_path 再丟給 Prettier，整個一行解決。如果你的系統沒有 jq，Mac 可以 brew install jq，Ubuntu 是 apt install jq。

如果你的專案不是用 Prettier 而是 ESLint，把 npx prettier --write 換成 npx eslint --fix 就好。

這個 hook 跟專案的 lint / format 規則綁在一起，建議寫在 .claude/settings.json 跟著 commit 給全團隊吃。

擋掉 rm -rf 之類的危險指令

把 hook 寫成一個獨立的 Shell script 會比較好維護，請你先建立 .claude/hooks/block-rm.sh：

1
2
3
4
5
6
7
8
9
10
11

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

# 只擋真正的 rm -rf / 或 rm -r /，後面接其他路徑（例如 /tmp/foo）放行
if echo "$COMMAND" | grep -qE 'rm[[:space:]]+-rf?[[:space:]]+/([[:space:]]|$)'; then
  echo "Blocked: 不允許從根目錄 rm -rf" >&2
  exit 2
fi

exit 0

這邊用 POSIX 字元類別 [[:space:]] 不用 \s，是因為 \s 是 GNU grep 的擴充，macOS 預設的 BSD grep 不一定支援，會讓比對整個失效。[[:space:]] 是 POSIX 標準寫法，Mac、Linux 各家 grep 都認得。

regex 那段 (/([[:space:]]|$)) 強制 / 後面要接空白或行尾，所以：

• rm -rf /：會擋掉
• rm -r /：會擋掉
• rm -rf /tmp/foo：不會擋掉，因為後面接了路徑不是空白或行尾

這個 pattern 故意寫得很保守，只擋字面上的 rm -rf / 跟 rm -r /。如果你想擋更兇一點（例如 rm -rf /*、rm -rf ~、rm -rf $HOME 這些變形），照同樣模式加幾條 grep -qE 串起來，每多一個 case 就 exit 2 即可。

然後打開在 .claude/settings.json 註冊：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

$CLAUDE_PROJECT_DIR 是 Claude Code 內建的環境變數，會自己變成專案根目錄（也就是你在哪邊呼叫專案，就會變成哪邊）。

Note
這個 hook 即使在 --dangerously-skip-permissions 模式下也會生效。PreToolUse 是在權限模式判斷之前就跑，所以 hook 是少數可以真正擋住「繞過權限」模式的機制。

這種安全防護建議寫在 .claude/settings.json commit 進 repo，全團隊都有保護。如果你只想自己保險，放 ~/.claude/settings.json 也行。

Compact 之後重新注入專案脈絡

Context 一旦被 Compact，Claude 常常會忘記某些重要約定。可以用 SessionStart 加 compact matcher，在每次壓縮完之後重新塞一段提醒：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo '提醒：套件管理用 pnpm 不要用 npm；commit 前一定要跑 pnpm test。'"
          }
        ]
      }
    ]
  }
}

SessionStart 跟 UserPromptSubmit hook 輸出到 stdout 的內容會被當成額外脈絡加進 Claude 的 context，這是它們跟其他事件不太一樣的地方。

如果你想塞動態內容（例如目前的 git 分支、未 commit 的檔案），把 echo 換成你的 script 就好：

1
2
3
4

#!/bin/bash
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
DIRTY=$(git status --porcelain | wc -l)
echo "目前分支：$BRANCH，未 commit 檔案數：$DIRTY"

這個 hook 寫在 .claude/settings.json 比較適合，因為「用 pnpm」「commit 前要跑 pnpm test」這種是專案內部約定，commit 進去其他人 clone 下來也直接吃得到，不會每個人都要自己設一次。

Mac 桌面通知

Claude 在等你授權 or 等下一個 prompt 的時候通知一下，這樣你可以放心去做別的事：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code 在等你\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Linux 把 osascript 換成 notify-send，Windows PowerShell 用 MessageBox.Show，邏輯都一樣。

Note
Mac 第一次跑可能沒反應，因為 osascript 是透過內建的 Script Editor app 發通知，要先到「系統設定 → 通知」找到 Script Editor 把通知權限打開才會出現。如果連 Script Editor 都沒看到，先在 Terminal 跑一次 osascript -e 'display notification "test"'，它就會出現在通知設定的清單裡。

桌面通知純粹是個人偏好，寫在 ~/.claude/settings.json 就好，不用 commit 進 repo。

把 Claude 的每個動作通知到 Discord

如果你不想開著終端機盯 Claude，或想把 Claude 在跑什麼丟到 Discord channel 跟團隊共享，可以用 PreToolUse hook 串 Discord webhook。

先到 Discord channel 設定產一個 webhook URL，然後在 shell profile 裡 export 出來（不要寫死在 script 裡，commit 進 repo 等於外洩）：

1

export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/你的-webhook-id/你的-token"

接著建立 ~/.claude/hooks/discord-notify.js：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

#!/usr/bin/env node
const WEBHOOK_URL = process.env.DISCORD_WEBHOOK_URL;

async function main() {
  // 讀進 Claude Code 從 stdin 餵進來的 JSON
  const chunks = [];
  for await (const chunk of process.stdin) chunks.push(chunk);
  const input = JSON.parse(Buffer.concat(chunks).toString());

  const toolName = input.tool_name || "未知工具";
  const toolInput = input.tool_input || {};

  // 組一個 Discord embed，讓訊息漂亮一點
  const embed = {
    color: 0x7289da,
    author: { name: `🔧 ${toolName}` },
    description: toolInput.file_path
      ? `\`${toolInput.file_path}\``
      : toolInput.command
        ? `\`\`\`bash\n${toolInput.command}\n\`\`\``
        : "",
    timestamp: new Date().toISOString(),
  };

  await fetch(WEBHOOK_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ embeds: [embed] }),
  });
}

main().catch(console.error);

最後在 ~/.claude/settings.json 註冊（用個人 settings 讓所有專案都生效）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/discord-notify.js"
          }
        ]
      }
    ]
  }
}

matcher: "" 是「不管什麼工具都通知」，這樣 Claude 不管要 Read、Edit、Bash 你都會在 Discord 看到一則訊息。如果你想根據工具種類顯示不同 emoji、顏色、欄位，照這個結構往下擴就好。

這整個 hook 是個人通知用、webhook URL 也是你私人的，寫在 ~/.claude/settings.json 個人層就好，不用 commit。

Note
Webhook URL 一定要透過環境變數讀，不要寫死在 script 裡。萬一你真的想跟團隊共用一個 webhook，hook 本身可以放 .claude/settings.json，但 webhook URL 還是只放在各自的 shell profile 或 .claude/settings.local.json（後者不會被 commit）。

Log 所有 Bash 指令

如果你想稽核 Claude 到底跑了哪些 Bash 指令，可以在 PostToolUse 加個一行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash.log"
          }
        ]
      }
    ]
  }
}

每跑一次 Bash 指令就會被追加到 ~/.claude/bash.log，事後翻很方便。這個是個人稽核用的，寫在 ~/.claude/settings.json 就好。

多個 hook 怎麼合併？

當你同一個事件設了好幾個 hook，它們會全部平行執行，不會誰擋誰，最後 Claude Code 把所有結果合併。PreToolUse 的權限決定採「最嚴格者勝」：deny 蓋過 ask、ask 蓋過 allow。

舉個實際的例子，你可以同時設「Log 所有 Bash 指令」跟「擋掉 rm -rf」兩個 hook：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

當 Claude 試圖跑 rm -rf /tmp/build 時，兩個 hook 會同時跑，log 會被寫進去，rm 會被擋掉。Log 不會因為 rm 被擋就漏記，因為兩個是各自獨立執行的。

怎麼確認 hook 有跑？

設好 hook 卻不確定到底有沒有觸發？Claude Code 提供兩個方式可以查。

第一個是 /hooks 指令，在 Claude Code 裡面直接打 /hooks 會跳出目前已設定的 hook 清單，按事件分組，每個都可以點進去看 matcher 跟 command。/hooks 是唯讀的，要改 hook 還是要編輯 settings.json。

第二個是 debug log，啟動時加 --debug-file /tmp/claude.log：

1

claude --debug-file /tmp/claude.log

然後另一個視窗開 tail -f /tmp/claude.log，每次 hook 觸發都會在 log 看到完整的 stdout、stderr、exit code。如果你只想看 hooks 相關的訊息不想被其他 debug 噪音淹沒，可以用 claude --debug hooks 加 filter。

延伸閱讀

• Claude Code 哪些檔案該 Commit？CLAUDE.md、Settings、Rules、Skills 完整解析：搞懂 .claude/settings.json 的層級之後再來看 hooks 會更清楚。
• Claude Code 內建 Tools 在做什麼？看懂它怎麼選工具：要寫 hook 必須先知道 matcher 對應的工具名稱。
• 比 MCP 更省 Token 的 Agent Skills：Skill 跟 Hook 是互補關係，Skill 給能力、Hook 給保證。

前言

這篇來聊一下寫部落格到底賺不賺錢這件事。先講我自己部落格的三大收益來源（Google AdSense、Buy Me A Coffee、Portaly）比例大約 8:1:1，然後著重聊 Google AdSense。內容包含 CPM 與 CPC 的差異、AdBlock 怎麼影響曝光收益、Google Analytics 月活躍流量、AdSense 成效報表（瀏覽量、曝光次數、點擊、單次點擊出價、網頁千次曝光收益），最後實際把月收益算給你看，並且聊一下我自己的廣告版位設計。

為什麼想寫這篇

最近有些朋友看到我有經營部落格，所以就很好奇經營部落格跟寫文章的收益如何，這一篇就是要來破解一下他們以為的「寫部落格收益很高」這個迷思 xD

其實這個誤會滿常見的，可是真正的收益跟想像差很多，所以乾脆寫一篇來破除迷思。標題寫「一個月幾萬美金都可能！」也是有點故意，這就是大家口中的標題殺，因為大多數人對寫部落格這件事，第一印象就是這個畫面（吧？）。

Note
這篇只聊 Google AdSense 這條主線，至於 Buy Me A Coffee 跟 Portaly 為什麼比例很小，講白了就是「不是每次都有人會抖內」，所以就不額外展開了。

如果你還沒看過我之前那篇 為什麼寫文章可以有收益？以 Google AdSense 與 Liker 為例，那篇是更早期關於部落格收益怎麼運作的入門介紹，這篇可以當成五年後的「真實業績驗收版」。

我的部落格收益拆解

先簡單列一下，目前我的部落格主要收益來源有這三種：

• Google AdSense
• Buy Me A Coffee
• Portaly

這三者的比例大概是 8:1:1，也就是說 AdSense 是真正的大宗，後兩者比較像「偶爾收到讀者鼓勵」的性質。所以接下來篇幅都會放在 AdSense 上，後兩者就點到為止。

AdSense 是怎麼算錢的？

AdSense 的收入概念其實不複雜，主要就是看廣告有沒有被人看到，以及看到的人有沒有點下去。當然細節會受很多因素影響，例如廣告類型、版位、主題分類等等，可是核心邏輯就是這兩件事。

而這兩件事又跟一個東西高度相關，就是流量。流量越多，曝光自然越多，能被點的機會也跟著越多。

我這個月的流量大概多少？

我用 Google Analytics 看了一下最近 30 天，活躍使用者大約是 1.8 萬人左右。

這個數字其實並不高，跟那些一個月幾十萬、甚至百萬流量的網站比起來差的可多了。

CPM 跟 CPC 是什麼？

接下來要來介紹 Google AdSense 的兩個重要概念：CPM 跟 CPC。

AdSense 的計價方式主要有兩種：

簡單來講，CPM 是「我這個廣告版位有人看到就有錢」，CPC 是「有人真的點進去才有錢」。

通常 CPC 的單價會比 CPM 高很多，原因也很合理：使用者真的點下去，代表他對廣告有興趣，可能會轉換成購買，所以廣告主願意付更多錢。CPM 的收益則是看版位、廣告類型，還有最重要的一點，使用者有沒有開 AdBlock。

只要使用者有開 AdBlock，那個版位的廣告請求根本不會跑出來，曝光、點擊都歸零，所以 CPM 跟 CPC 都沒得收。這也是為什麼有些網站會跳訊息請讀者把站台加進 AdBlock 的白名單。

但我個人滿不喜歡這種感受的，畢竟有一種「強迫讀者」的感覺，還是希望能在不干擾閱讀的前提下，讓讀者願意支持就好，所以以我來講，我就只是放這種提示為主。

畢竟這樣比較能夠維持讀者體驗，長期來講對部落格的成長也比較有幫助。

真實數字：我這個月到底賺多少？

ok 講那麼多概念，我們直接看 AdSense 上的「成效」報表。我這邊拉出「最近 28 天」跟「再往前 28 天」做比較，比較看得出趨勢。

報表上會有以下幾個欄位：

• 瀏覽量（Page Views）
• 網頁千次曝光收益（Page RPM）
• 曝光次數（Impressions）
• 點擊（Clicks）
• 單次點擊出價（CPC）
• 網頁點擊率（CTR）

我自己最近 28 天的數字大概是這樣：

老實講這個 CPC 很低，平均一次點擊只有 0.21 美金，相較之下有些主題（金融、保險、軟體訂閱）的 CPC 可以飆到 1 美金以上。網頁千次曝光收益 0.73 美金也不算高。

那這數字大概怎麼換算成總收入呢？最直觀的方式是直接用「曝光次數 × 千次曝光收益 / 1000」，因為 AdSense 報表的「千次曝光收益（RPM）」本身就是把整個月 CPC + CPM 所有廣告收益加總後，再正規化成「每 1000 次曝光的均值」，所以反推回來就能還原回月收入：

1

收入 = 曝光次數 × 千次曝光收益 / 1000

代到我自己的數字裡：

1

44.82 ≈ 61400 × 0.73 / 1000

一個月大概是 44.82 美金（AdSense 報表上實際顯示 44.84，差 0.02 是因為 0.73 這個 RPM 本身在報表上就被四捨五入過，反推回去自然會掉一點點精度）。

聽起來好像還不錯？可是這只是 Google 給的數字，最後實際入帳還要扣稅金、金流跨境手續費，實拿會更少一點。而且這個曝光跟點擊量也不是每個月穩穩的，只要哪一個月沒持續更新文章 or 主題沒踩中搜尋熱度，流量馬上就會掉，收入也跟著縮水，底下是我沒有認真經營部落格的 Google Analytics 流量趨勢：

當時的一日廣告費用大概 0.01 美金不到。

這邊也放上寫這篇文章時的 Google AdSense 收益：

我的廣告版位設計

廣告版位這件事是 AdSense 主很愛糾結的點。我自己的部落格廣告版位設計，大方向都是「盡量不要影響閱讀」，所以主要放在這幾個位置：

• 文章開頭
• 文章結尾
• 文章列表（每五篇穿插一個廣告）
• 側邊欄左右兩側
• 定位錨點（類似浮動廣告，可是只會固定在最上方 or 最下方）

Note
我個人在逛自己的部落格時，大多都會打開 AdBlock，因為 Google AdSense 有嚴格規範，不允許自己點擊自己的廣告，之前有過一次不小心點到幾次，結果被 Ban 兩個月 QQ…

如果以「壓榨收益」的角度來看，這個密度其實算少。要真的把收益拉到極致，還可以加上：

• 文章內文中間插入廣告（讀到一半被打斷）
• 覆蓋式廣告（看一半畫面被廣告蓋住）
• 強制看完倒數才能關掉的廣告
• 自動播放有聲音的影片廣告

這些版型確實會大幅拉高收益，可是讀者體驗就會直接被拖到地板。我自己當讀者也很討厭這類體驗，看到一半被廣告打斷我會直接關掉分頁，連回訪都不會了，更不用說訂閱 RSS or 推薦給朋友。

關於廣告版位的選擇與優化，我以前寫過一篇 如何讓 Google 廣告（AdSense）增加收益？，裡面有更細的版位分析，有興趣的話可以延伸閱讀。

那到底能不能月入幾萬美金？

回到一開始的標題殺問題：寫部落格可以月入幾萬美金嗎？答案是可以的，但門檻很高。

你可能要同時滿足以下條件：

• 流量等級要在百萬層級（不是 1.8 萬）
• 主題切在高 CPC 的領域（金融、保險、SaaS、購物）
• 廣告版位策略夠激進，可是又不能讓讀者直接列為 AdBlock 名單
• 多語系經營（特別是英文流量）拉高整體 CPM 跟 CPC 的天花板，不局限於特定國家
• 文章持續產出、SEO 持續維護

少了任何一項，數字都會直接砍半甚至更多。

所以對絕大多數獨立部落客來講，把 AdSense 當主要收入是不切實際的，比較合理的定位是「副業 + 長期累積資產」。

結語

寫這篇不是要勸退你寫部落格，反過來說，我反而覺得寫部落格的好處遠遠不只在「賺錢」這件事上，像是建立個人品牌、整理知識、訓練表達能力，這些長期收益比廣告分潤值錢太多了。我之前寫過 AI 當道，為什麼我還是推薦寫部落格 也有聊到這塊，有興趣可以延伸看。

可是如果你今天就是衝著「靠寫部落格賺錢」這個動機進來，那我希望這篇能幫你校正期待，寫部落格賺錢是真的，可是不會像你以為的那麼香，比較像是把它當成一個會慢慢長大的存錢筒，而不是一個提款機。

那希望這一篇有讓你對寫部落格的真實收益狀況多一點了解哩～

Note
Claude Code 有三種排程：Routines（雲端，關電腦也會跑）、Desktop scheduled tasks（本機，要 App 開著）、/loop（session 內排程，要終端機開著）。/schedule CLI 是建立 Routines 的入口，最短 1 小時間隔，預設只能推 claude/ 前綴分支，要推 main 要去網頁打開 Allow unrestricted branch pushes。

前言

其實我一直都有在使用 Claude Code 的 /schedule 指令，而這個指令就是在建立一個排程任務，每天都會在我指定的時間執行，跑完之後我也會請它 push 到我的 GitHub 上。但，我滿常遇到一個狀況，也就是隔天打開 GitHub 一看，GitHub 分支反而變成了 claude/main-xxxx 這種，而不是我期望的 main 分支 QQ…

所以這篇就來把 Claude Code 的排程功能寫下來，順便把這個讓我很困擾的 claude/main-xxxx 記錄下來並搞清楚。

哦對了，如果你之前看過 Claude Cowork Dispatch 與 Remote Control 那篇，那這篇可以當作另一條延伸路線：Dispatch 跟 Remote Control 是讓你現在用手機遠端控制，而排程是讓 Claude 自動在你不在的時候幫你做事哩。

Claude Code 有三種排程

在進到 /schedule 之前，Claude Code 其實有三種不同的排程方式，這邊也準備一張表格比較一下差異：

了解這三種排程差異之後，接下來我就會著重於 Routines（Cloud） 的部分來介紹。

Routines 是什麼？

Routines 簡單來講，就是你把 prompt 跟它要用的 Repo 等等，放到 Anthropic 雲端，然後它會自己在你設定的時間 or 條件下幫你跑你要的任務。

跟一般的 Claude Code session 最大的差別有兩個：

1. 它跑在 Anthropic 的雲端環境：不是你的電腦，所以你關電腦它也照跑、出門也照跑、睡覺也照跑。
2. 它是自主執行的：不會跳出權限提示（也就是 Yes、No），會完全依照你給的 prompt 自己跑完，所以 prompt 也必須非常明確，不然它可能會做出你沒預期到的行為。

Note
如果想要讓自己的每個月訂閱額度不被浪費的話，其實我個人滿推薦使用 Routines 來做一些定期性的任務，例如每天幫我檢查有沒有新的 PR 需要 review、每週幫我整理一下這週的 commit log、每月幫我開一個 PR 更新一下 README 的 stats 圖表之類的。

而 Routines 的觸發類型目前有三種：

但這一篇我們就著重於介紹 /schedule 哩～

建立排程：用 /schedule

建立 Routines 有兩種方式：

1. 網頁的 claude.ai/code/routines
2. CLI（終端機） /schedule

不論是哪一種都可以，反正兩邊改的是同一筆資料，所以你在哪邊建立、編輯都會即時同步到另一邊。

基本用法就是這樣：

1

/schedule

直接打 /schedule 不帶任何東西，Claude 會用對話的方式引導你建立，問你 prompt 寫什麼、要選哪個 Repo、跑多久一次等等。

如果你已經很清楚要建什麼，也可以直接把描述寫在後面：

1

/schedule daily PR review at 9am

或是想要一次性的提醒：

1

/schedule in 2 weeks, open a cleanup PR that removes the feature flag

Claude 會把你寫的時間轉成具體的 timestamp，跟你確認後存起來。

Note
/schedule CLI 只能建立 Schedule 觸發類型，如果要加 API or GitHub event 觸發，要到 claude.ai/code/routines 網頁端編輯。

除了建立之外，CLI 也支援管理已經存在的 routines：

Note
真的懶的話，其實你叫 AI 用 /schedule 幫你建排程也可以…

為什麼我請它推到 main 卻變成 claude/xxx？

了解了基本的建立流程之後，接下來要來講一下我前面所講的 「明明請它推到 main 卻變成 claude/xxx」的問題。

當你在 Routines 裡跑一個會 push 程式碼的 prompt 時，Claude 預設只能推到 claude/ 前綴的分支。所以即使你的 prompt 寫「處理完直接 push 到 main」，Claude 也只能開一個像 claude/main or claude/update-main-xxxx 之類的分支推上去，不會真的動到你的 main。

這不是 bug 是 feature（真的），這樣的設計原因是「避免 routines 不小心改到重要的分支」。畢竟排程任務是自主運作的、沒有任何權限提示也沒人在旁邊盯著，如果它能直接寫 main，一個寫壞的 prompt 就可能讓一個正式的產品雞飛狗跳。

那怎麼解？兩種選擇：

1. 接受預設行為：讓它推 claude/xxx 分支，然後你開 PR review，最建議的工作流，畢竟排程任務沒有人在旁邊看，先進到一個獨立分支，等你有空再 review 跟合併，相對安全很多。
2. 打開 Allow unrestricted branch pushes：如果你真的想讓它直接推到 main，可以在 Edit routine 的 Permissions 區塊把對應 Repo 的「Allow unrestricted branch pushes」打開，這樣就沒有分支前綴的限制了，不過要小心你的 prompt 寫好寫滿，確保它不會做出你不想要的改動。

如果你真的就是要讓它直接推到指定分支，可以這樣做：

1. 到 claude.ai/code/routines 點進你的 routine
2. 按鉛筆圖示進入 Edit routine
3. 找到下方的 Permissions 區塊
4. 把對應 Repo 的「Allow unrestricted branch pushes」勾起來
5. 存檔

Note
如果你的 main 是受保護的、設了 branch protection rule 的話，就算打開 Allow unrestricted branch pushes，GitHub 那邊還是會擋下來。這時候要嘛在 protection rule 加例外，要嘛還是讓它走 PR 流程比較實際。

排程跑在哪、會用到哪些東西？

除了分支推錯之外，還有幾個 Routines 相關的細節，第一次設排程很容易忽略，這邊一起講一下。

每次都是從 default branch 重新 clone

Routines 每跑一次，都是從你選的 Repo 的 default branch 重新 clone 一份來跑，不會延續上次的 working tree。所以你不能寫一個排程是「接續昨天那次跑到一半的事」，每次都要當作從零開始。

如果你的任務需要參考上次的狀態，可以把狀態寫到 Repo 的某個檔案 or 連接上第三方服務。

一次性排程不吃 daily cap

Routines 有 daily run cap（一天最多能跑幾次的限制），但 one-off 排程不會吃這個 cap，它只會吃你訂閱方案的一般用量。所以如果你想用排程當「兩週後幫我做某件事」這種一次性提醒，可以放心開很多個，不會把 daily cap 用爆。

管理 routines

設好的 routine 要管的話有兩條路。

CLI 端用前面提到的 /schedule list、/schedule update、/schedule run，做基本的列表、編輯、立刻觸發。

網頁端則是到 claude.ai/code/routines，點進每個 routine 的詳細頁，這邊可以做更多事：

• Run now：立刻觸發一次，不等下一個排程
• Repeats 開關：暫停 or 恢復排程，暫停不會刪掉 routine 本身
• 編輯：改名稱、prompt、Repo、環境、Connectors、觸發類型
• 刪除：移除這個 routine，過去跑過的 session 還會留在 session 列表

另外每次 routine 跑完都會在你的 session 列表開一個新 session，你可以點進去看 Claude 做了什麼、review 變更、開 PR、甚至接著對話繼續做下去。

總結

Claude Code 的排程功能講複雜也不複雜，主要就是搞清楚三種排程的差別、/schedule 怎麼用、然後記得預設只能推 claude/ 前綴分支這件事，剩下的就是依照你的需求調整觸發類型跟環境設定。

我自己後來的習慣是：日常的「每天跑一次某個小事」用 Routines 設 daily、需要存取本機檔案的 batch 任務用 Desktop scheduled task、想在當下 session 裡反覆 poll 某個狀態就用 /loop，三個各有各的場景。

至於那個一直推到 claude/xxx 分支的問題，知道是設計使然之後就釋懷了，反正讓它推 claude/ 分支然後 PR review 也比較安心。如果你跟我一樣有遇到這個困惑，希望這篇有幫你省下翻文件的時間哩～

延伸閱讀

如果你想把 Claude Code 玩得更全面，也可以接著看：

• Claude Cowork Dispatch 與 Remote Control - 用手機遠端控制你的 AI Agent：另一條讓你不用守在電腦前的路線，但要的是「現在就用手機操控」而不是「自動排程」。
• 想用 Claude Code 開發？這篇帶你從入門到進階：Claude Code 完整指南，從基本操作到進階開發技巧。
• Claude Code Auto Memory 是什麼？自動記憶功能完整教學：搭配排程一起用，讓 Claude 在每次排程跑起來時都記得你的偏好。

前言

相信很多寫 CSS 的人都有遇過這個情境，明明在自己的元素上加了 overflow: scroll，但打開 Chrome 卻看不到捲軸，傳給同事看，他那邊卻又跑出一條灰灰的捲軸，明明用的都是 Chrome，怎麼會有這種差異？這一篇就從 overflow 屬性是什麼開始講。

先聊聊 overflow 是什麼

在分析問題之前，先稍微回顧一下 overflow 這個屬性是什麼。

簡單來講，overflow 是用來決定當一個元素裡面的內容超出它本身的寬高時，要怎麼處理那一段超出的部分，這個屬性算是 CSS 裡面非常基本但又非常常用的東西。

舉個例子，假設我有一個寬 200px、高 100px 的 div，但裡面塞了一段超長的文字 or 一張比 200px 還寬的圖片，這時候畫面就會發生兩件事：

• 內容直接跑出（溢出）容器到外面去
• 內容被切掉，看不到後面那一段
• 出現捲軸，讓使用者自己滾動

那這要怎麼解決呢？那就要來講講 overflow 了。

overflow 的四個常見屬性

overflow 屬性有四個比較常用的屬性，這邊用一張表格快速看一下：

這邊要特別拉 scroll 跟 auto 出來講，因為這兩個屬性最容易搞混，但它們兩者差異只有一個小地方，也就是 scroll 是「永遠都會出現捲軸」，但 auto 則是「內容超出時，需要才會出現捲軸」。

那為什麼 overflow: scroll 在我電腦上看不到捲軸？

這是因為 macOS 預設使用的是 「隱形捲軸（Overlay Scrollbar）」，這種捲軸只有在你正在捲動時才會浮現出來，平常是隱藏的，而且不會占據版面的空間。但你同事如果是用 Windows，那邊的捲軸是 「古典捲軸（Classic Scrollbar）」，會固定保留位置而且永遠看得到。

所以兩個人開同一個網頁、同一個版本的 Chrome，但看到的視覺結果就會不同，根本原因不是 Chrome 不一樣，而是底下的作業系統不一樣。

macOS 的「隱形捲軸」

在 macOS 上，捲軸的顯示行為是由系統設定決定的，查看方式是「設定 → 外觀 → 顯示捲軸」，這邊有三個選項可以選：

通常預設屬性是「自動依揵滑鼠或觸控式軌跡板」，也就是當你用的是觸控板 or Mac 內建的軌跡板時，它就會走「捲動時」的行為，有點饒舌對吧？簡單來講，也就是平常完全看不到捲軸，只有你在捲的當下會浮出一條半透明的細條，停下來幾秒它又會自動淡出消失。

而 Chrome、Safari 跟其他大多數的 Mac 瀏覽器，預設都會跟著這個系統設定走，所以即便你在 CSS 寫了 overflow: scroll，瀏覽器還是會用「隱形捲軸」的方式渲染，不會把捲軸固定地顯示在那邊。

那要怎麼確認到底是不是這個原因呢？很簡單，你只要走兩個步驟驗證：

1. 把 macOS 的**「顯示捲軸」切到「總是」**
2. 重新整理一下你的瀏覽器（或者重新開啟）

這時候捲軸就會直接固定地出現了，這代表 CSS 沒寫錯，是作業系統的設定在控制視覺呈現。

為什麼 Windows 沒這個問題？

因為 Windows 從以前到現在都是用「古典捲軸」，捲軸會固定占住版面右側（大約 15 ~ 17px 寬），不管你有沒有在捲都看得到，也不會自動淡出消失。

所以你同事打開同一個頁面時，那條灰灰的細長捲軸就直接掛在右邊，他寫的 overflow: scroll 看起來就是 CSS 預期的樣子，沒有「捲軸到底跑去哪了」的疑問。

這邊順便提一個容易忽略的點，如果你都在 Mac 上開發、可是實際使用者大多用 Windows，那你看到的內容寬度其實會比使用者那邊還多一段（被捲軸吃掉的那段）。做 RWD 切版時，建議借同事的 Windows 開一下看看版面有沒有跑掉，免得交付後才發現右邊有點擠。

那怎麼讓兩邊看起來一樣？

如果你希望不管使用者用什麼系統都看得到捲軸（例如怕 Mac 使用者根本不知道內容還可以往下捲），這邊有幾種做法可以選：

方法一：用 ::-webkit-scrollbar 強制顯示

最直接的做法是用 ::-webkit-scrollbar 這個 CSS 偽元素去自訂捲軸樣式，只要你給它一個明確的 width 或 height，Chrome 就會自動把這個元素的捲軸從隱形捲軸切換成古典捲軸，永遠固定顯示。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

.scroll-box {
  width: 300px;
  height: 200px;
  overflow: scroll;
}

.scroll-box::-webkit-scrollbar {
  width: 8px;
  height: 8px;
}

.scroll-box::-webkit-scrollbar-thumb {
  background-color: #888;
  border-radius: 4px;
}

.scroll-box::-webkit-scrollbar-track {
  background-color: #f0f0f0;
}

寫完之後你會發現 Mac 上的 Chrome 終於把捲軸固定顯示出來了，而且因為它已經變成古典捲軸，會吃掉一段內容寬度，這時候版面就會跟 Windows 上看到的比較接近。

可是這個做法有兩個小坑要記得：

• ::-webkit-scrollbar 是 Webkit / Blink 系列才支援的非標準屬性，Chrome、Edge、Safari、Opera 都吃，可是 Firefox 不吃
• iOS Safari 對 ::-webkit-scrollbar 的支援也很有限，大部分情況下還是會走系統的隱形捲軸

方法二：用標準化的 scrollbar-width 跟 scrollbar-color

如果你不想用非標準屬性，CSS 後來也有把捲軸樣式標準化，新增了 scrollbar-width 跟 scrollbar-color 兩個 W3C 標準屬性（出自 CSS Scrollbars Module Level 1），跟 ::-webkit-scrollbar 比起來最大的差異就是它有規格背書。

1
2
3
4
5
6
7

.scroll-box {
  width: 300px;
  height: 200px;
  overflow: scroll;
  scrollbar-width: thin;
  scrollbar-color: #888 #f0f0f0;
}

• scrollbar-width 可以設 auto、thin 或 none，分別對應「預設粗細」、「細捲軸」、「隱藏捲軸」
• scrollbar-color 接收兩個顏色值，前者是捲軸 thumb 的顏色，後者是 track 的底色

可是支援度要先注意一下，Firefox 從 64 就支援這兩個屬性了，Chromium 系列（Chrome、Edge）要到 Chrome 121 之後才支援，Safari 則是要 Safari 26.2 之後才有完整支援。如果你的網站還要兼容比較舊的瀏覽器，建議把 ::-webkit-scrollbar 一起寫上去當 fallback。

Note
MDN 文件有提到，當 scrollbar-width 或 scrollbar-color 設成非 auto 的值時，會直接蓋掉 ::-webkit-scrollbar 的樣式。所以兩個一起寫的時候，要注意誰會贏。

為什麼不用 scrollbar-gutter？

看到這邊你可能會想說，CSS 不是還有 scrollbar-gutter 可以拿來保留捲軸位置嗎？那直接用它來解這個問題不是更省事？

可惜不行，這個屬性對 macOS 的隱形捲軸沒效果。

scrollbar-gutter: stable 原本的設計目的是保留捲軸需要的版面空間，避免內容因為捲軸有無而抖動。可是 MDN 文件上有明確寫一行：當瀏覽器使用隱形捲軸時，scrollbar-gutter 不會有任何效果。

簡單來講，它要解決的是古典捲軸那種會占空間的場景下，內容因為捲軸出現/消失而跳動的問題。可是 macOS 預設用的是隱形捲軸，本來就不占空間，自然也沒東西好保留。

所以如果你的目標是讓 Mac 上的 Chrome 永遠看得到捲軸，scrollbar-gutter 解決不了這個問題，還是要回去用 ::-webkit-scrollbar 或 scrollbar-width。

結語

回到開頭那個「同事看得到、你看不到」的情境，這個問題的根源其實不是 CSS 寫錯，也不是 Chrome 哪裡壞掉，而是作業系統層級的捲軸機制本來就不一樣 — macOS 預設走隱形捲軸，Windows 預設走古典捲軸，兩邊對 overflow: scroll 的視覺呈現自然就不同。

知道這件事之後，下次再遇到一樣的狀況就不用懷疑自己 CSS 寫錯，可以直接想到是系統設定差異，再依需求選 ::-webkit-scrollbar or 新版的 scrollbar-width 補上一致的視覺。

如果你對瀏覽器底層怎麼把 CSS 渲染成你看到的畫面有興趣，可以再看看 前端工程師應該要懂的瀏覽器渲染機制 這一篇，裡面把 Render Process 從 DOM 樹一路到 Composite 的流程整理得滿完整的，跟這篇可以串成更完整的「為什麼瀏覽器會這樣顯示」的脈絡。

前言

VSCode 1.109 推出新的整合瀏覽器（Integrated Browser）後，只要 workbench.browser.openLocalhostLinks 這個設定被打開，點終端機或聊天視窗裡面的 localhost 連結就會被自動拉進編輯器內顯示，畫面又小又難用。所以這一篇會記錄一下 workbench.browser.openLocalhostLinks 跟 simpleBrowser.useIntegratedBrowser 這兩個關鍵設定怎麼關，以及還是想偶爾用一下整合瀏覽器時可以怎麼從命令面板手動叫出。

為什麼會變成這樣？

這個行為其實不是 VSCode 一直都有的，而是從 1.109 版（差不多是 2026 年 1 月）開始新增了一個叫做「整合瀏覽器（Integrated Browser）」的功能，當這個功能開著時，只要 VSCode 偵測到你點的是 localhost 連結，就會優先把這個連結拉進編輯器內顯示，這樣你就不用切換到其他應用程式去看畫面。

立意上來講是不錯，但對許多開發者來講其實是滿困擾的，因為編輯器本來就已經被切成檔案總管、編輯區、輸出視窗等好幾塊，再多塞一個瀏覽器進來，能用的空間就會變得很小，你想在裡面測 RWD、開 DevTools 都不太方便 QQ…

整合瀏覽器跟 Simple Browser 有什麼關係？

如果你有用 VSCode 一段時間了，那你應該會聽過 Simple Browser，這是 VSCode 早期就有的一個內建瀏覽器套件，但它的限制比較多，例如：

• 只能顯示靜態頁面
• 不能登入需要驗證的網站
• 不會保留 cookie

所以以前大家頂多拿來瞄一下 localhost 起來有沒有跑而已。

那麼新版的整合瀏覽器跟 Simple Browser 之間又是什麼關係呢？

簡單來講，整合瀏覽器是 Simple Browser 的進階版本，但兩者目前是並存的，並不是新的把舊的取代掉，你可以透過設定來決定命令面板叫出來的是哪一個。

整合瀏覽器強化了 Simple Browser 所缺乏的能力，所以它可以做到：

• 登入需要驗證的網站（cookie 跟登入狀態都會被保留）
• 瀏覽任何頁面，不限 localhost
• 內建 DevTools，可以直接檢查元素
• 把選到的元素丟給 Copilot 當作上下文

簡單來講，就是 VSCode 把一個比較接近 Chrome 的小瀏覽器塞進了編輯器裡，讓你不需要離開 VSCode 也能完整看一個網頁，而不是像以前 Simple Browser 那樣只能看個半套。

那為什麼點連結會被自動拉進去？

整合瀏覽器本身只是「多了一個可以用的瀏覽器」，會發生「點連結就被搶走」這件事，是因為 VSCode 提供了一個叫做 workbench.browser.openLocalhostLinks 的設定，只要這個設定是打開的，VSCode 任何地方（終端機、聊天視窗、Markdown 預覽、輸出面板等等）點到的 localhost 連結都會被導去整合瀏覽器，而不是丟給你系統預設的瀏覽器。

Note
1.109 釋出說明裡面寫的是「可以打開這個設定」，所以理論上預設是關閉的，但有些情境下會在你沒注意的時候被打開（例如點過某個提示、or 裝了某個套件偷偷幫你開），這時候你就會發現怎麼點 localhost 連結都跑去 VSCode 內。

解決方法

知道是哪個設定在搞鬼之後，把它關掉就解決了，這邊提供兩種方式，看你比較順手哪一種。

方法一：透過設定面板關掉

首先打開 VSCode 的設定面板：

• macOS：Cmd + ,
• Windows / Linux：Ctrl + ,

接著在最上方的搜尋框輸入：

1

workbench.browser.openLocalhostLinks

接著你應該會看到這個設定，把它的勾勾取消掉就好，這邊不需要重開 VSCode，會立刻生效。

方法二：直接改 settings.json

如果你比較喜歡改 JSON 檔案（or 有同步多台機器設定的需求），那也可以走這條路。

先按 Cmd + Shift + P（Windows 是 Ctrl + Shift + P）打開命令面板，然後輸入：

1

Preferences: Open User Settings (JSON)

選擇之後它會幫你開啟 settings.json，接著我們只要在裡面加入這個設定：

1
2
3

{
  "workbench.browser.openLocalhostLinks": false
}

存檔後就會立刻生效，再去終端機點一次 localhost 連結，畫面就會回到你系統的預設瀏覽器了哩～

順便處理：Simple Browser 套件自己的設定

關掉 workbench.browser.openLocalhostLinks 之後，理論上 localhost 連結就會回到正常，但這邊要特別提一下，VSCode 還有一個跟整合瀏覽器有關的設定叫做 simpleBrowser.useIntegratedBrowser，這個其實是「Simple Browser 套件自己的設定」，並不是 VSCode 核心提供的，從命名上其實就可以看出來。

從這張表你應該可以發現，前綴名稱其實就反映了它的出處，workbench.* 是 VSCode 自己的，而 simpleBrowser.* 則是屬於 Simple Browser 這個內建套件的，所以如果你關了核心設定之後還是發現從命令面板叫出來的瀏覽器跑去新版整合瀏覽器，那就是這個套件設定還開著，搜尋一下名稱關掉就好。

還是想偶爾用一下整合瀏覽器？

把自動接管關掉之後，整合瀏覽器並不是就完全不能用了，如果哪天你想在編輯器內快速確認一下某個畫面，還是可以手動把它叫出來。

一樣按 Cmd + Shift + P（Windows 是 Ctrl + Shift + P）打開命令面板，接著輸入：

1

Simple Browser

按 enter 後輸入你想看的網址，整合瀏覽器就會在編輯器內開出一個分頁，這樣需要的時候自己叫出來，不需要的時候連結也不會被搶走。

結語

整合瀏覽器這個功能本身其實是不錯的，但預設行為對於習慣用外部瀏覽器當主力的人來講就比較困擾，那個小視窗實在難以取代日常開發在用的 Chrome 或 Edge，因此這時候把它關掉是比較好的選擇。

希望這一篇有讓你對 VSCode 整合瀏覽器的自動接管行為與關閉設定有更近一步的認識哩～如果你還想再順手把 Mac 端的開發環境整理一下，可以再看看 Mac 上裝軟體到底該用哪種方式？Homebrew、官網下載、curl 完整比較 這一篇，跟這一篇可以串成一條更完整的環境整理流程，我們下篇文章見囉～

前言

如果你有用過 Claude Code、Cursor、Codex 這類 AI Coding 工具，應該都遇過類似的瓶頸：剛上手覺得超神奇，可是真的拿來開發一個有規模的專案，各種雷就跑出來 — context 爆掉之後 AI 忘光、改 A 壞 B 改了又改、AI 改著改著把好的 code 也蓋掉、好幾個檔案一起被改沒辦法回滾等等。

這些都不是工具的問題，是跟 AI 協作的流程沒建立起來。

說到這邊有件事滿值得提一下，Andrej Karpathy 是 2025 年 2 月（原始 tweet）提出 Vibe Coding 這個詞的人，到了 2026 年 4 月他自己在 Sequoia Ascent 2026 的演講（標題「Software 3.0, Agentic Engineering, and Jagged Intelligence」）上直接升級了這個概念，提出 Agentic Engineering（代理工程）。演講裡關鍵的一句話是：

「Vibe coding raises the floor. Agentic engineering is about extrapolating the ceiling.」

翻成白話就是：Vibe coding 是抬升底線，讓沒寫過 code 的人也能做出東西；Agentic engineering 是抬升天花板，是專業工程師該有的工作方式。

那 agentic engineer 跟以前的 vibe coder 差在哪？根據演講的核心訊息，重點不再是描述需求讓 AI 寫然後直接 ship，而是 AI 扮演實作者、你扮演監督者，要做的幾件事大致包含：設計規格、監督計畫、檢查 diff、寫測試、建立評估迴圈、管理權限、隔離 worktree、維持品質。換句話說，agentic engineer 不會盲目接受 AI 生成的 code，而是用工程紀律包住 AI 速度。

之前我寫過 淺談 AI Vibe Coding 當今主流的 BDD 與 SDD 跟 想開始 Vibe Coding？新手推薦先搞懂的這些基礎知識 這兩篇，前者偏方法論、後者偏新手該補的基礎技能，可是都還停在 vibe coding 框架。這一篇就直接升級，用 agentic engineering 的紀律把整套實戰流程攤開來講，每個環節都附可以直接抄走的範本，最後用一個個人電商 MVP（Nuxt 3 + Supabase + Stripe）的案例走一遍完整流程。

Note
為什麼一定要有紀律？根據 CodeRabbit 2025 年 12 月發布的「State of AI vs Human Code Generation」報告（分析了 470 個 GitHub open-source PR，320 個 AI co-authored + 150 個 human-only），AI 寫的 code 比人寫的多 1.7 倍 major bug、整體資安問題多 1.57 倍，其中 XSS 漏洞高達 2.74 倍、不安全的密碼處理多 1.88 倍。AI 生成的速度很快可是品質沒保證，靠的是你流程設計接住它的失誤。

Vibe Coding vs Agentic Engineering：2026 你該選哪個？

在進實戰流程之前，先用一張表把兩者差別講清楚：

從這張表可以看出來，兩者不是替代關係，而是適用情境不一樣。週末做個小工具玩玩，vibe coding 完全沒問題；可是要做給別人用的東西、要長期維護的專案，就得切換到 agentic engineering 模式。

接下來這篇的 SOP，全部都是站在 agentic engineering 的紀律寫的。

完整流程一張圖：一個功能從需求到 ship

在進細節之前，先用一張流程圖把整套 SOP 壓縮成一個功能的完整協作流程。這張圖有三個角色 — 你（使用者）、Leader（主 Claude）、員工（Sub-agent + Skill），整體 7 個 step：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

[使用者]                    [Leader / 主 Claude]            [員工 / Sub-agent + Skill]
   │                              │                                  │
   │ ① 提需求                     │                                  │
   ├─────────────────────────────▶│                                  │
   │                              │ ② plan mode 拆解需求             │
   │                              │   （必要時呼叫 sub-agent 探索）   │
   │                              ├─────────────────────────────────▶│
   │ ⚠ 需求有疑問時，Leader       │   產出 docs/tasks.md             │
   │   主動 AskUserQuestion       │◀─────────────────────────────────│
   │◀─────────⇄───────────────────│                                  │
   │                              │ ③ 開發（UI 切給 ui-engineer）    │
   │                              ├─────────────────────────────────▶│
   │                              │   同一輪補單元測試                │
   │                              │◀─────────────────────────────────│
   │                              │ ④ Code Review                    │
   │                              │   （另開 session or sub-agent）   │
   │                              ├─────────────────────────────────▶│
   │                              │   fresh context 抓 bias           │
   │                              │◀─────────────────────────────────│
   │                              │ ⑤ 驗收 + 三段驗證                 │
   │                              │   typecheck + test + build        │
   │                              ├─────────────────────────────────▶│
   │                              │   基於 spec（CLAUDE.md / AGENTS）│
   │                              │◀─────────────────────────────────│
   │ ⑥ 回報 + 更新 ROADMAP/tasks  │                                  │
   │◀─────────────────────────────│                                  │
   │ ⑦ 你 review diff + commit / push                                │
   ├──────────⇄───────────────────│                                  │

幾個關鍵看點：

• 你只在 ①、⑥、⑦ 三個 step 親自參與（提需求、看回報、review diff + commit），中間 ② → ⑤ 都是 Leader 在 orchestrate
• 理想狀態下 Leader 偏向 orchestrator 角色 — 拆解、分派、收回報，把實作切給員工。實務上主 agent 還是常常會自己接手寫 code，除非你明確設計 delegation 流程（例如 prompt 內直接寫請呼叫 X sub-agent 處理），不要假設它會自動 route 出去
• ⚠ step 是 Anthropic 官方推薦的 interview pattern — 需求模糊時 Leader 主動用 AskUserQuestion 反問你，避免下游做錯方向
• ④ Code Review 一定要 fresh context — 由另一個 session 的 Claude or sub-agent 來做，避免 self-confirmation bias
• ⑤ 驗收測試的依據是 spec（CLAUDE.md / AGENTS.md），不是 Leader 自己腦補的標準

每個 step 對應到後面章節的細節：① ② 在 一、規劃階段、③ 在 二、員工分工 + 三、開發紀律、④ ⑤ 在 四、收尾驗證、⑦ 在 三、開發紀律 的 commit 切點。

如果中間 Leader 走偏了，回到 五、失誤救援 的回滾決策表；雷被抓到之後寫進 六、Memory 系統 變長期 rule。

一、規劃階段：Spec → Plan → Tasks 三層落檔

Agentic engineering 的第一個原則就是 規劃要文件化。業界主流框架例如 GitHub 在 2025 年釋出的 Spec Kit（Specify → Plan → Tasks → Implement 四階段，每階段都會產出 spec.md / plan.md / tasks.md 這類檔案）、Anthropic 官方的 Claude Code best practices（Explore → Plan → Implement → Commit 四階段，plan mode 可以按 Ctrl+G 把 plan 打開到編輯器直接編輯落檔），核心精神都一致 — plan 跟 spec 應該寫成可讀可改的檔案，而不是只活在對話裡。

具體要分三層：

1. Spec（規格）：這個專案在做什麼、給誰用、邊界在哪
2. Plan（計畫）：要做哪些 feature、什麼時間做完
3. Tasks（任務）：當前任務拆成哪些步驟、做到哪了

三層各自落檔，每層解決一個 context 問題。

1.1 Spec：寫一份 CLAUDE.md（搭配 AGENTS.md）當專案憲法

開工前要先搞清楚一件事：不同 AI Coding 工具讀的設定檔不一樣。

• Claude Code 只讀 CLAUDE.md，不讀 AGENTS.md（Anthropic 官方文件明確說「Claude Code reads CLAUDE.md, not AGENTS.md」）
• 其他工具（Cursor、Codex、Windsurf、Aider 等）讀 AGENTS.md

AGENTS.md 是什麼？

AGENTS.md 是 OpenAI 在 2025 年 8 月主導推出的開放標準，跟 Amp、Google Jules、Cursor、Factory 等多家 AI 工具廠商合作發展，2025 年 12 月由 OpenAI 捐給 Linux Foundation 旗下的 Agentic AI Foundation（AAIF），跟 Anthropic 捐的 MCP（Model Context Protocol）、Block 捐的 Goose 並列為 AAIF 三大創始項目。截至 2026 年 5 月，全球已經有超過 6 萬個開源專案在用它，支援 Amp、Codex、Cursor、Devin、Factory、Gemini CLI、GitHub Copilot、Jules、VS Code 等 20+ 個 AI Coding 工具。

該怎麼配置？

最實用的做法是 兩個檔案都寫，但內容不重複：

• AGENTS.md 放專案規範本體（給跨工具團隊共用）
• CLAUDE.md 第一行 @AGENTS.md 把 AGENTS 內容 import 進來，下面再加 Claude Code 專屬規則 + @ import ROADMAP / tasks

或者更省事的做法是 ln -s AGENTS.md CLAUDE.md 建立 symlink，內容一份兩個檔名共用（Windows 需要 Administrator 權限 or Developer Mode，沒開的話用 @AGENTS.md import 比較保險）。

如果你只用 Claude Code 不在意跨工具，直接寫 CLAUDE.md 即可，AGENTS.md 不用寫。

CLAUDE.md 範本

直接 copy 這個結構到你的專案根目錄 CLAUDE.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# 專案名 - Claude Code Instructions

@AGENTS.md

## 開工前必讀
@docs/ROADMAP.md
@docs/tasks.md

## Project Overview
（一兩句話：這個專案是什麼、給誰用）

## Build & Test
- 安裝：pnpm install
- 開發：pnpm dev
- 測試：pnpm test（全綠才能 commit）
- 打包：pnpm build
- 型別檢查：pnpm typecheck

## Code Style
- 使用 ES modules（import/export），不用 CommonJS
- 命名：composable 用 useXxx、service 用 xxxService、純函式用 camelCase
- 縮排：2 空格
- 引號：單引號

## Testing Rules
- 每次改 code 同一輪就把測試補上，不可拖到下一個 task
- 測試檔命名：xxx.test.ts，跟實作放同一個資料夾
- 純函式優先抽出來測（比 mock 容易）

## Git Workflow
- commit message 用 Conventional Commits（feat / fix / test / refactor / docs / chore）
- 一個邏輯改動一個 commit，不要堆
- 主分支：main；功能分支：feature/xxx

## Security
- 不要把 API key、token、密碼寫進 code
- .env 檔案不可 commit
- 敏感檔案：.env*、*.key、credentials.json

## 明確排除的事
- 不引入 [某類功能]，原因：[原因]
- 不使用 [某個技術]，原因：[原因]

Note
上面範本第 3 行 @AGENTS.md 是雙檔架構用的。如果你只寫 CLAUDE.md 不寫 AGENTS.md，把這行刪掉即可（否則 Claude Code 會抱怨找不到 AGENTS.md）。
反過來如果走雙檔架構：AGENTS.md 的內容跟上面 CLAUDE.md 範本一樣，只是不需要 @AGENTS.md 那行（因為它本身就是被 import 的目標）；而且 ## 開工前必讀 區塊建議只放在 CLAUDE.md 裡，因為 @import 是 Anthropic 對 CLAUDE.md 的擴充、其他工具實作 AGENTS.md 不一定支援。

@import 機制（這是 Claude Code 的關鍵）

注意上面範本第一個區塊 ## 開工前必讀 裡的 @<path> 語法 — 這是 Anthropic 對 CLAUDE.md 的擴充語法（官方文件確認），AI 啟動時讀到 @<path> 會自動把那個檔案的內容也載進 context，遞迴 最多 5 hops 深，relative path 跟 absolute path（例如 @~/.claude/personal-rules.md）都支援。

這個機制超關鍵，因為 Claude Code 啟動時 預設只會自動載入 CLAUDE.md 本身（以及 ancestor 路徑的 CLAUDE.md），docs/ 底下的 ROADMAP.md、tasks.md 不會被自動讀到。如果你只寫 ROADMAP 沒在 CLAUDE.md 裡 @ 引用，AI 開新 session 進來根本看不到你的計畫，等於白寫。

Note
@<path> 是 Anthropic 對 CLAUDE.md 的擴充，AGENTS.md 規格本身沒有規定 import 語法，其他工具實作 AGENTS.md 不一定支援 @import。所以跨工具情境，重要規範建議直接 inline 寫進 AGENTS.md 比較保險，不要假設其他工具會跟著解析 @import。Claude Code 這邊照常透過 @AGENTS.md 把整份內容拉進來、再透過 @docs/ROADMAP.md 把計畫接上。

1.2 Plan：寫一份 ROADMAP.md 列功能跟階段

CLAUDE.md（搭配 AGENTS.md）是專案憲法、不太會變；ROADMAP.md 是這個 sprint or 這個月要做什麼 feature 的計畫，會隨開發推進更新。

ROADMAP.md 範本

放在 docs/ROADMAP.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 專案名 ROADMAP

## 願景
（一兩句話：這個專案要解決什麼問題、給誰用）

## Week 1：MVP
- [ ] 功能 A：[簡述行為跟驗收條件]
- [ ] 功能 B：[同上]

## Week 2：補強
- [ ] 功能 C：[同上]
- [ ] 功能 D：[同上]

## 待評估
- 功能 X：可能做、可能不做，看 Week 1 完成度
- 功能 Y：同上

## 明確排除的事
- 功能 Z：因為 [原因]

## 明確排除的事 這一塊很重要，AI 容易自己腦補功能、越界做事，把不做的事明文列出來可以幫你卡住範圍。

1.3 Tasks：寫一份 tasks.md 同步當前進度

第三層是當前任務的進度追蹤。AI 內建有待辦清單工具（例如 Claude Code 的 todo 系統），可是這個本質上活在 context 裡，跑 /compact、關掉 session 重開、context 一爆掉，這份清單就跟著消失了。所以更穩的做法是同時請 AI 把進度寫到實體檔案。

tasks.md 範本

放在 docs/tasks.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 本次任務：[ 任務簡述 ]

## 待辦清單
- [x] 1. 讀懂需求、plan 已落到 docs/ROADMAP.md
- [x] 2. 拆解子任務
- [ ] 3. 實作 A
  - [ ] 3-1. 寫 A.composable
  - [ ] 3-2. 同步寫 A.composable.test
- [ ] 4. 實作 B
  - [ ] 4-1. 寫 B.service
  - [ ] 4-2. 同步寫 B.service.test
- [ ] 5. 跑 typecheck + test + build 三段驗證
- [ ] 6. commit + push

## 進行中
3-1：寫 A.composable，目前卡在 [描述]

## 完成紀錄
- 2026-XX-XX：plan 確認、tasks 拆完

開工前直接跟 AI 說：先列待辦清單、同步寫到 docs/tasks.md，每完成一項就更新檔案。這樣即使隔天重開新 session，AI 一進專案讀檔案就接得回去。

二、員工分工：你的三種 AI 員工配置

Karpathy 在演講裡有強調 agentic engineering 的 agentic 二字 — 在 2026 年的現在，你不再是親手寫 code 的工程師，而是 管理一群 AI 員工的監督者。Claude Code 在 2025-2026 演進出三種員工配置，每一種解決不同的問題。

2.1 Skill：注入主 agent 的標準流程包

Skill 是放在 .claude/skills/<name>/SKILL.md 的 markdown 指令包，當 Claude 偵測到任務匹配 skill 的描述就會自動 load 進主 context。Skill 跟主 agent 共用 context、共用模型，適合重複會做的標準動作。

Skill 範本（API 慣例）

.claude/skills/api-conventions/SKILL.md：

1
2
3
4
5
6
7
8
9
10
11
12

---
name: api-conventions
description: REST API design conventions for this project
---

# API Conventions

- URL 路徑用 kebab-case：/api/user-profiles
- JSON property 用 camelCase：userId, createdAt
- list endpoint 一律支援分頁：?page=1&pageSize=20
- API 版本放在 URL 路徑：/v1/、/v2/
- 錯誤回應格式：{ code, message, details? }

Note
想了解 Skill 完整機制，可以看我之前寫的 比 MCP 更省 Token 的 Agent Skills。

2.2 Sub-agent：獨立 context、獨立權限的專職員工

Sub-agent 跟 Skill 最大的差別是：sub-agent 有 獨立的 context window、獨立的 system prompt、獨立的 tool 權限，甚至可以跑不同的模型。Claude 主 agent 把任務派給 sub-agent 之後，sub-agent 在自己的 context 裡做事，做完只回傳摘要給主 agent，主 agent 的 context 完全不會被汙染。

放在 .claude/agents/<name>.md：

Sub-agent 範本（security-reviewer）

.claude/agents/security-reviewer.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

---
name: security-reviewer
description: 替新寫的 code 做資安 review
tools: Read, Grep, Glob, Bash
model: opus
---

你是資深資安工程師。Review code 時關注：
- Injection 漏洞（SQL、XSS、command injection）
- 認證跟授權瑕疵
- code 裡的 secrets / credentials
- 敏感資料處理

請給出具體的行號跟修法建議。

Sub-agent 範本（test-writer）

.claude/agents/test-writer.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

---
name: test-writer
description: 替剛寫好的 composable / service 補對應的單元測試
tools: Read, Edit, Bash
model: sonnet
---

你是專門寫單元測試的 AI engineer。

收到任務時：
1. 先讀目標檔案、理解函式 / composable 的行為
2. 列出 happy path + edge case + error case 三類測試
3. 用 Vitest 寫成 .test.ts 檔案
4. 跑 pnpm test 確認全綠
5. 若有 case 沒過，回報失敗 case 給主 agent 決定怎麼處理

Sub-agent 範本（ui-engineer）

.claude/agents/ui-engineer.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

---
name: ui-engineer
description: 處理 Tailwind class、元件樣式、design system 相關修改
tools: Read, Edit, Glob
model: sonnet
---

你是專門處理 UI/UX 的 frontend engineer。修改畫面樣式時遵守：

- filled input 不要再加 border
- focus ring 走 design system token，不要 hardcode 顏色
- touch target 至少 44px（包含按鈕、icon button、可點區塊）
- 間距用 design system 級距（mt-2 / mt-4 / mt-6 / mt-8），不要亂塞 mt-5 mb-3 沒邏輯的數字
- 顏色用 design system color token，不要 hardcode hex 色碼
- 不要用 !important 覆蓋既有樣式 — 找到根本原因改正確的層級
- RWD 優先寫 mobile，再用 md:、lg: 加大版斷點

收到任務時：
1. 先讀目標元件、確認既有 pattern 跟 token 用法
2. 修改 Tailwind class（不寫自訂 CSS 除非真的必要）
3. 改完後對照範例畫面 / Figma（如果有的話）確認視覺一致

什麼時候該選 Skill、什麼時候該選 Sub-agent？

2.3 Agent Teams：跨 session 平行的進階模式

Agent Teams 是 2026 年新出的進階模式 — 多個 Claude 跑在獨立 worktree、透過 git 協調工作，每個 agent 認領自己的任務、自己 merge、自己解衝突。實務經驗大致是 3-5 個 parallel agents 算是 sweet spot，超過 10 個之後成本提高但效益不一定增加。

這個模式對新手過於複雜，可以先掌握 Skill + Sub-agent 兩種就好，等到專案大到一個人 + 一個主 Claude 跑不動的時候再考慮。

三、開發紀律：三條每天都要堅持的鐵則

進入實作階段之後，三條紀律是每天都要堅持的，每一條都是直接接住 AI 失誤的網。

3.1 改 code 同一輪對話就把測試補上

這條規則最常拿出來提醒 AI：每次改 code 都要同一輪對話就把測試補上，不要拖到下次再說「再開一個 task 統一補」。

為什麼這麼堅持？因為 AI 開發有個很容易踩的雷，就是改 A 壞 B。你今天叫它調整某個 composable 的邏輯，它跑出來的 code 表面上看起來都對，可是其實已經 side effect 改到別的地方了，你眼睛看不出來。而測試就是接住這種 side effect 的網。

那為什麼要強調同一輪呢？因為事後補的測試很容易變成為了讓 code pass 的測試，而不是真的在驗證行為的測試。同一輪補的時候，AI 寫實作跟寫測試的上下文是連在一起的，需求、邏輯、case 三件事都還活著；如果你拖到下一個 task 才補，那時候上下文已經漂移，AI 補出來的 case 通常只能蓋到表面，蓋不到真正的 edge case。

補測試提示範本

開工前 / 每次新功能前直接跟 AI 說：

1
2
3
4

這個任務每改一個檔案，同一輪就把對應的測試補上來。
補測試要列為跟實作並列的子任務（不是放在實作下面的 sub-task），
這樣才不會做完實作就漏掉。
最後跑 pnpm test 確認全綠才算這個 task 結束。

3.2 動 UI 一律切給專門的 Skill 或 Sub-agent

只要這次修改牽涉到 UI/UX（畫面排版、元件樣式、Tailwind class 調整等等），都直接呼叫專門處理 UI 的員工去做，而不是讓主 agent 自己亂改。

為什麼這樣分？

簡單來講就是術業有專攻。主 agent 在做架構決策、寫邏輯的時候很強，可是一旦動到 UI/UX，它常常會犯一些通病：例如用一堆 !important 覆蓋既有樣式、配色完全沒有 design system 概念、間距亂塞 mt-5 mb-3 沒邏輯。

UI 相關的員工通常會內建 design system 知識、配色規範、可用性原則，它知道 filled input 不要再加 border、focus ring 要走 token、touch target 至少 44px 這些常識。

UI 切員工提示範本

1
2
3
4
5

這次要動 [元件名 / 畫面區塊]，目標是 [描述要達成的效果]。
請呼叫 UI 專門的員工處理（前面 2.2 的 ui-engineer sub-agent，
or 如果有裝 plugin 例如 ui-ux-pro-max 也可以呼叫那個）。
主 agent 只負責決定動哪個元件、想要什麼方向，
實際改 Tailwind class 那一刻交給專門員工接手。

3.3 一個邏輯改動就一個 commit，不要堆成大塊

第三條是 commit 紀律。AI 如果沒有明確規則，常常會一次改十幾個檔案塞進一個 commit，等到後面某一段需要 revert 的時候，發現整包綁在一起，根本沒辦法乾淨地拆出來。

所以規則一定要明文化：一個邏輯改動 = 一個 commit。例如：

• 補 A 元件的測試 → 一個 commit
• 修 B 路由的 bug → 另一個 commit
• 重構 C 共用邏輯 → 另一個 commit

這樣未來要 revert 任何一段都不會牽動其他工作，搭配第五段會講的回滾策略，補救成本可以壓到最低。

commit message 範本（Conventional Commits）

1
2
3
4
5
6

feat: 新增 A 功能
fix: 修 B 元件的 router bug
test: 補 C composable 的測試
refactor: 抽出 D 共用邏輯
docs: 更新 ROADMAP.md
chore: 升級套件版本

AI commit 切點提示範本

開工前跟 AI 說：

1
2
3
4
5
6

commit 切點規則：一個邏輯改動就一個 commit。
- 不要把實作 + 測試 + 修 bug 堆在同一個 commit
- 補測試跟實作要拆開 commit（test: 跟 feat: 各一個）
- 重構獨立 commit、不混進其他改動
commit message 用 Conventional Commits 格式
（feat / fix / test / refactor / docs / chore）。

四、收尾驗證：三層安全網接住 AI 失誤

寫完 code 不等於做完，收尾階段有三層安全網要過，每一層接的失誤類型都不一樣。

4.1 第一層：typecheck + test + build 三段驗證

每次任務告一段落要交付的時候，固定請 AI 跑三段驗證：

1. pnpm typecheck（or tsc --noEmit）— 確認型別都過得了
2. pnpm test — 確認既有測試全綠
3. pnpm build — 確認可以打包出乾淨的產物

這三段抓的是不同層的問題：

• typecheck 抓型別錯誤，例如 AI 把 User 物件傳到一個吃 string 的 function
• test 抓行為錯誤，例如 AI 改了一個 function 結果該回傳 true 的 case 變成 false
• build 抓打包之後才會爆的錯誤，例如某個 import 路徑 dev mode 跑得起來、production build 卻爆掉

只跑其中一段是不夠的，這三段加在一起才是相對完整的安全網。

交付前 checklist 範本

1
2
3
4
5
6

- [ ] pnpm typecheck（or tsc --noEmit）通過
- [ ] pnpm test 全綠
- [ ] pnpm build 成功
- [ ] 自己跑一次實際功能、用瀏覽器戳一下畫面
- [ ] git status 沒有意外的檔案改動
- [ ] commit message 符合 Conventional Commits 格式

4.2 第二層：Writer / Reviewer 雙 Claude 模式

這是 Anthropic 官方在 best practices 推薦的進階工法。簡單講就是 開兩個 Claude session，一個負責寫、一個負責 review，因為 Claude review 自己剛寫的 code 會有 confirmation bias、不容易抓到問題；換一個 fresh context 的 Claude 來 review，能抓到更多 edge case。

實作方式：

更進階的做法是把 Reviewer 設成一個 sub-agent（像前面 2.2 的 security-reviewer），這樣每次寫完都可以一鍵呼叫 review，不用手動開新 session。

4.3 第三層：AI 引用的版本號、套件名、API 自己去官方對一次

第三層安全網是抗 AI 過期記憶用的：每次 AI 在寫 code 時引用了套件版本、API 用法、雲端服務後台這類更新很快的東西，都自己打開官方文件對照一遍，不要直接讓 AI 的記憶 ship 進專案。

為什麼這麼龜毛？因為 AI 的 training data 是有截止日期的，特別是套件版本、API 規格、雲端後台 UI 這些東西更新非常快，AI 用記憶答出來的常常已經是好幾個月前的版本了。例如它可能寫某個套件的 API，可是其實在新版裡早就改名了；或者它告訴你某個雲端服務在後台點 X 設定，可是後台介面早改版了。

AI 引用必查清單

1
2
3
4
5
6
7
8
9
10
11
12
13

看到 AI 寫的 code 出現以下引用，自己打開官方文件對一次：

[必查]
- 套件 API 用法（特別是 major 版本可能改過）
- 雲端服務後台 UI / 設定步驟（AWS、GCP、Cloudflare、Firebase console 等）
- 環境變數 / 設定檔欄位名
- 框架 / SDK 版本對應的語法（Vue 3 vs Vue 2、Nuxt 3 vs 2 等）
- 第三方服務 API 規格

[不用查]
- 純語法（JS 內建陣列方法、字串處理等）
- 純邏輯（演算法、純函式）
- 你自己專案內的 module 跟 type

五、失誤救援：回滾決策表

實戰中一定會遇到 AI 改壞 code 的時候，這時候最浪費時間的反應是在錯的方向上繼續加東西想 fix — 越救越大坑。所以一定要有明確的回滾判斷尺。

Claude Code 在 2026 年加了一個叫 /rewind 的功能（or Esc + Esc），可以回到任一個 checkpoint，連 Claude 改過的 code state 都會還原。這個是第一層救援工具。

Note
一個重要 caveat — Anthropic 官方明確說 checkpoint 只追蹤 Claude 改過的檔案，不追蹤 Bash command 造成的檔案變更（例如 npm install 改的 node_modules、rm 刪掉的東西、build 產出的檔案）。這部分要靠 git 才能 recover，所以 git commit 紀律不能省。

判斷尺一句話：壞掉的是執行細節？還是規劃方向？

回滾決策表

從這張表可以看出來，回滾不是失敗、是流程的一部分，把它當成抗 AI 失誤的工具來用，整個開發節奏會穩很多。

六、Memory 系統：兩層架構 + 正向 pattern 範本

最後一個環節是 memory 系統的設計，這個環節做好之後，前面所有的紀律都會變成 AI 主動會做的事，不用每次都手動提醒。

memory 要分兩層設計：

6.1 全域層：用 ~/.claude/CLAUDE.md 或 ~/.claude/rules/ 放跨專案通用規則

跨專案會通用、你明確想讓 Claude 每次都遵守的規則（套件管理慣例、補測試紀律、不過度設計、不擅自擴大範圍等），按 Anthropic 官方文件有兩個位置可以放：

• ~/.claude/CLAUDE.md — 整份單一檔案、每次 session 自動載入，適合放 5-10 條核心原則
• ~/.claude/rules/<topic>.md — 按主題拆檔案（一條 rule 一個檔），也是每次 session 自動載入，好處是可以用 YAML frontmatter paths: 欄位做 path-scoped rules（例如某條 rule 只在處理 src/api/** 時才載入）

新專案直接共用不用重教。

Note
順帶釐清一個常見誤會 — Claude Code 還有一個叫 Auto memory 的功能，是 Claude 自己累積的（不是你手寫的），存在 ~/.claude/projects/<project>/memory/，按專案分而不是全域。本章談的「全域層規則」指的是你手動寫給 AI 看的規範，跟 Auto memory 是不同的東西。Auto memory 完整機制可以看我之前寫的 Claude Code Auto Memory 是什麼？。

全域規則範本（pnpm 慣例）

~/.claude/rules/pnpm.md：

1
2
3
4
5
6
7
8
9
10
11
12
13

---
name: 套件管理用 pnpm
description: JS/TS 專案一律用 pnpm 不要用 npm
type: feedback
---

JS/TS 專案預設用 pnpm，不要用 npm。

**Why:** lock file 慣例統一、硬碟空間節省、monorepo 友善。

**How to apply:** 看到 package.json 預設下 pnpm install / pnpm run xxx。
如果專案有 package-lock.json 但沒有 pnpm-lock.yaml，
先問使用者要不要遷移到 pnpm。

全域規則範本（補測試紀律）

~/.claude/rules/testing.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

---
name: 改 code 同一輪就補測試
description: 每次程式異動都要在同一輪對話補上對應的測試
type: feedback
---

每一次新增或修改程式碼，都必須在同一次工作中補上對應的測試。

**Why:** 事後補的測試容易變成「為了 pass 而 pass」，蓋不到 edge case。

**How to apply:**
- 寫新 composable / service / 純函式時，同一次任務內加 *.test.ts
- 改既有檔案造成行為變化時，擴充既有測試 or 新增測試
- 純函式優先抽出來測（比 mock 容易得多）
- 跑 pnpm test 全綠才算完成
- 補測試列為跟實作並列的子任務

全域規則範本（嚴守交付範圍）

~/.claude/rules/minimal-scope.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

---
name: 嚴守指定交付範圍
description: 使用者說只要 X 時不要順手附帶其他檔案
type: feedback
---

使用者交付任務時明確說只改 X 就只改 X，不要順手改其他檔案。

**Why:** 擴大範圍會引入未授權的變更，使用者花更多時間 review，
甚至引入 regression。

**How to apply:**
- 每次任務開頭明確列出範圍
- 超出範圍的發現先記下來再問，不要先動

6.2 專案 AGENTS.md / CLAUDE.md 放專案特定 rule

專案層放這個專案才用得到的設計決策、產品邊界、踩過的雷。判斷尺：這條 rule 換到別的專案還會用嗎？ 會用就放全域、只在這專案用就放專案層。

如果你想了解 Claude Code memory 完整機制，可以參考我之前寫的 Claude Code Auto Memory 是什麼？自動記憶功能完整教學。

6.3 寫 rule 的時候，正向 pattern 比禁令式更有用

最後一個關鍵：寫 rule 的時候要刻意混搭禁令式跟正向 pattern，光寫禁令是不夠的。

從這張表可以看出來，禁令式只能擋住雷、無法主動引導正確的產出，所以要搭配正向 pattern 一起用。

正向 pattern 範本

~/.claude/rules/plan-template.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

---
name: 成功 plan 文件的範本
description: AI 寫 plan 文件時應該參考的正向結構
type: feedback
---

寫 plan 文件時，應該包含以下四塊：

1. **目標**：一兩句話寫清楚要解決什麼問題、給誰用
2. **任務拆解**：每一個子任務獨立列出來，含驗收條件
3. **不做的事**：明確排除（很重要，AI 容易越界）
4. **開發紀律備忘**：套件管理、測試、commit 切點等

範例參考專案的 docs/ROADMAP.md。

**Why:** 禁令式 rule 只能擋住雷，正向 pattern 才能引導出對的東西。

**How to apply:** 收到寫 plan、規劃功能、整理 ROADMAP 這類任務時，
先讀過這份結構再動筆。

兩種一起用最有效：禁令防雷、正向引導。

實戰案例：個人電商 MVP 從 Spec 到 Ship

講完六大環節，最後用一個比較貼近真實工作的案例走一遍完整流程：做一個個人小型電商 MVP，賣自製商品、要能收得到錢。

技術棧用 Nuxt 3 + Vue 3 + Tailwind + Pinia + Supabase（DB + Auth）+ Stripe（付款）+ Vercel（hosting）。這個 stack 是 2026 年小型電商 MVP 滿主流的組合 — 後端不用自己架、付款交給 Stripe、hosting 一鍵部署。

Step 1 — 寫 CLAUDE.md（搭配 AGENTS.md）當專案憲法

開新專案第一件事是寫 CLAUDE.md（如果跨工具團隊也同步寫一份 AGENTS.md，CLAUDE.md 第一行 @AGENTS.md import 進來）。電商比一般工具多了 金錢 / 安全 / RLS 這幾個重點區塊，所以憲法裡要明文寫清楚：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54