Terry Yao's Blog

Claude Code output style 踩坑：keep-coding-instructions、設定值與生效時機

Claude Code output style 踩坑：keep-coding-instructions、設定值與生效時機

閱讀時間約 5 分鐘

問題

我想用 Claude Code 的 output style 修一個問題：它的輸出常常冒出一堆自造術語和代號，我看不懂。照理說寫一個 style 檔、要求它講白話就好，結果過程踩了一連串設定雷，卡了很久。

下面每條都標來源：官方文件有寫的附連結（文件內容以 2026-10-11 查閱時為準），只有我實測的標「實測」。

坑一：keep-coding-instructions 預設是 false

自訂 style 的檔案放在 ~/.claude/output-styles/<名稱>.md（user 層，所有專案都看得到），或專案裡的 .claude/output-styles/（Output styles 文件）。

frontmatter 裡的 keep-coding-instructions 預設是 false。不設的話，自訂 style 會把 Claude Code 系統提示裡「軟體工程指示」那一段拿掉——怎麼界定改動範圍、怎麼寫註解、怎麼驗證工作，這些都不見了（同上文件的 Frontmatter reference 與 How output styles work 段）。

我只是想改「說話方式」，不想改「做事方式」，所以一定要加：

---
name: Plain Language
description: 少用自造代號，術語第一次出現要解釋
keep-coding-instructions: true
---

要注意的是：style 不是把整份系統提示換掉，而是加上你的指示；但工程指示那一段，在 keep-coding-instructions 沒設的情況下會被拿掉。文件另外提到，較短版本的系統提示本來就不含那一段，這時這個欄位沒有作用。

坑二：outputStyle 的值要對上 style 名稱，大小寫也算

啟用方式有幾種：/config 裡選 Output style、/output-style <名稱> 指令，或直接在 settings 檔寫 "outputStyle": "<值>"。

我當時卡在「這個值要填 frontmatter 的 name，還是檔名？」。官方文件的答案：

  • style 名稱預設是檔名，frontmatter 有設 name 就用 name。
  • outputStyle 的值要完全符合 style 名稱，區分大小寫。對不上的值不會報錯，而是直接回到 Default style。

（Output styles 文件：Change your output style 與 Create a custom output style）

所以「設了卻沒反應」，我遇到的原因就是這類：檔案有 name: Plain Language，settings 卻填了檔名；或大小寫不同。用 /config 的選單選，它會寫入正確的值，最省事。

坑三：/output-style 指令的版本變動

我踩坑的時候（2026-08），這個指令在我的版本裡已經不能用，只能走 /config。我當時記下的是「在 v2.1.91 移除」，但對照官方 changelog，查到的紀錄是：

  • v2.1.73：/output-style 標為 deprecated，改用 /config；同時「output style 固定在 session 開始時決定，以利 prompt caching」。
  • v2.1.269：重新加回 /output-style [name]，可以列出並切換 style。

（Claude Code CHANGELOG，2026-10-11 查閱）

「v2.1.91 移除」這點在 changelog 裡沒找到對應紀錄（未查證）。結論：遇到指令不存在，先看自己的版本號，再查 changelog；/config 是各版本都能用的路。

坑四：改了不生效——什麼時候要重開

我當時的經驗是「改了要開新 session 才生效」。這跟 v2.1.73 那條「style 固定在 session 開始時決定」吻合。

現在的文件說法比較細（2026-10-11 查閱）：

  • 切換 style：從下一則訊息開始生效。v2.1.251 以前要 /clear 或開新 session 才會套用。
  • 新建或修改 style 檔：終端機版的 Claude Code 只在啟動時讀 style 檔，執行中改檔要重開 Claude Code 才讀得到。

（Output styles 文件）

也就是說，「切換」和「改檔內容」是兩件事。我當時是一邊改檔一邊測，難怪怎麼試都沒變化。

怎麼預防再次發生

  • 自訂 style 只想改說話方式，就一定加 keep-coding-instructions: true。
  • outputStyle 用 /config 選，不要手打；手打就對照 frontmatter name，大小寫一致。
  • 改了 style 檔就重開 Claude Code，不要指望 /clear。
  • 照著網路文章（包括這篇）設定前，先確認自己的版本號：這個功能在 changelog 裡來回改過好幾次。
  • Claude Code output styles
  • keep-coding-instructions
  • prompt caching 與 session 生效時機

關係圖譜