Slash Command 進階：與子代理和工具協作

前兩篇講了 slash command 是什麼（一個 Markdown 檔案）以及怎麼用 ! 前綴把 shell 輸出注入 context。這篇要談的是更重的事：怎麼讓一條 command 編排 Claude Code 裡最強的幾個能力——檔案引用、子代理、MCP 工具——同時把權限管好。

寫到這一層，command 就不再只是「提示詞快捷鍵」，而是一個可複用的小型工作流。

`@file` 引用：比 `!cat` 更適合的靜態注入

!cat file.md 確實能把檔案內容塞進 context，但它走 shell，有幾個缺點：每次觸發都要起子行程；路徑裡有空白或特殊字元時得額外跳脫；Claude Code 不會把它當成「一個檔案」，只會當成一段純文字。

@ 引用是原生的：

---
description: 依據專案規範審查變更
---

參考以下規範：

@.claude/context/coding-standards.md
@.claude/context/security-checklist.md

現在審查下方 git diff 的變更，把所有違反規範的地方都點出來。

!`git diff HEAD`

@路徑 告訴 Claude Code「把這個檔案當附件掛進對話」。兩者的差異：

情境	用 `!cat`	用 `@`
路徑來自參數（`$ARGUMENTS`）	✅ 只能用 `!cat`	❌ `@` 不展開變數
固定的專案規範、範本	⚠️ 能用但笨重	✅ 原生、省一次 shell
動態內容（diff、log、測試結果）	✅ 必須 `!`	❌ 做不到

一句話：靜態檔案用 @，動態輸出用 !，參數路徑用 !cat $ARGUMENTS。

`allowed-tools`：給 command 劃出權限邊界

預設情況下，command 執行時模型能用 session 內所有工具。這不一定是你想要的——例如 /review 是唯讀審查任務，你可不希望它「順手」改了一行程式碼。

在 frontmatter 加上 allowed-tools，命令執行期間就只有列出的工具能用：

---
description: 唯讀程式碼審查
allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
---

審查目前分支與 master 的差異，唯讀不改。

!`git diff master...HEAD`

幾個重點：

Bash(git diff:*) 是細粒度授權——只允許 git diff 開頭的 bash 呼叫，git push 會被擋掉
Read / Grep / Glob 明確只開唯讀工具
沒列 Edit / Write，模型就算想改也呼叫不到

反過來也行，像 /deploy 這類高權限 command：

---
description: 部署當前分支
allowed-tools: Bash(kamal deploy:*), Bash(git push:*), Read
---

把「這條命令能幹嘛」寫死，比每次執行時靠人工去按 bash 核准按鈕可靠多了。

呼叫子代理：把吃 context 的活隔離出去

有些任務會把主對話的 context 整個吃光——巡幾十個檔案找某個函式的所有呼叫點、跑一輪程式碼庫統計、抓一大段 log 來分析。直接在主對話裡做，幾千行輸出留在 context 裡，後面對話就變慢、變笨。

正確做法是把這種活丟給 subagent：子代理在獨立的 context 裡跑，跑完只把結論帶回主對話。command 裡只要明講就行：

---
description: 深入調查某個符號的所有用法
allowed-tools: Task
---

使用 Explore 子代理，深入調查以下符號的所有用法：$ARGUMENTS

子代理需要涵蓋：
- 所有呼叫點（含測試檔）
- 涵蓋到的業務場景
- 是否有等價的替代實作

子代理回來後，只給我一份 300 字以內的摘要，別貼原始程式碼片段。

觸發 /trace SomeClass#some_method，Claude Code 會起一個 Explore 子代理併發掃程式碼庫，主對話這邊只收到萃取後的結論。沒有 grep 輸出、沒有檔案片段，context 乾乾淨淨。

再往前推一步：

---
description: 並行調查三個候選方案
allowed-tools: Task
---

同時起 3 個子代理，分別調查以下三條實作路徑：

1. 現有的 ActiveJob + Sidekiq
2. Solid Queue
3. 自建輕量佇列

每個代理回報：工作量、風險、對現有程式碼的侵入程度。三份結論都回來後，我自己做比較。

三個子代理併發跑，主對話只要等一次。這是 command 能提供的最大槓桿之一——把「要燒很多 token 才能得到結論」的研究型任務，變成一鍵觸發的工作流。

呼叫 MCP 工具：讓 command 伸進外部系統

如果 session 裡接了 MCP server（Linear、GitHub、Sentry、自建資料庫代理等等），command 可以直接指示模型去呼叫這些工具：

---
description: 依 Linear issue 產出實作 todo
allowed-tools: mcp__linear__*, Read, Grep
---

讀取 Linear issue $ARGUMENTS 的完整描述和留言。

結合程式碼庫現況（用 Grep/Read 自己找相關檔案），列一份實作 todo：
- 需要改哪些檔案
- 每一步是獨立 commit 還是一起
- 有沒有需要先跟 PM 確認的模糊地帶

不要開始寫程式碼，只出計畫。

mcp__linear__* 授權整組 Linear MCP 工具，模型可以拉 issue 詳情、留言、狀態。整條 command 就成了「從 ticket 到實作計畫」工作流的入口。

要注意：在 allowed-tools 裡寫 MCP 工具名時要用完整前綴（mcp__<server>__<tool>），不然授權不生效。

command 組合的陷阱：slash 不會遞迴展開

一個很常見的誤解：在 /review 的檔案裡寫 /test，以為這樣會觸發 test command。不會。 slash command 只會在使用者輸入的最上層展開一次，command 內部的 /xxx 只是純文字，模型會讀到，但 Claude Code 不會去執行。

想組合多條 command，正確的做法有幾種：

做法 A：把共用邏輯抽到 context 檔案，各 command 用 @ 或 !cat 引用

@.claude/context/review-checklist.md
@.claude/context/security-checklist.md

做法 B：在 command 裡寫「就像 /review 那樣做」加上重複的關鍵指令

不優雅但有效。只要提示詞夠清楚，模型會照同一套路走。

做法 C：讓一條 command 用 Task 工具起子代理，子代理的 prompt 裡再複用同一組 context 檔案

真正的工作流編排最後都走這條路。父 command 負責調度和彙整，子代理負責執行具體步驟。

要避免的反模式：把 command 寫成幾百行，試圖一條指令做完所有事。 粒度一崩，維護成本飆升，而且一次執行就把 token 預算吃光。

三件套的使用時機

@、!、子代理、MCP 工具都湊齊後，Claude Code 裡給 command 注入「外部能力」的機制基本上就到齊了。怎麼選：

需求	首選
固定的規範、範本、上下文文件	`@file` 引用
即時狀態（diff、log、測試結果、資料庫查詢）	`!shell` 注入
參數化的檔案內容	`!cat $ARGUMENTS`
吃 context 的調查、跨檔案搜尋	透過 Task 的 subagent
外部系統（issue tracker、監控、正式機資料）	MCP 工具 + `allowed-tools`
多步驟序列或並行工作流	父 command 調度子代理

權限邊界要用 allowed-tools 明講，特別是團隊共用的 command——把能做什麼寫死，比靠每次人工核准靠譜。

一個接近正式環境的例子

把上面這些拼起來，看一條「依 Linear ticket 調研實作路徑」的 command：

---
description: 根據 Linear ticket 產出實作方案
allowed-tools: mcp__linear__*, Task, Read, Grep, Glob, Bash(git log:*)
---

## 上下文

@.claude/context/architecture.md
@.claude/context/coding-standards.md

## 目前程式碼庫狀態

!`git log --oneline -10`

## 任務

抓 Linear ticket $ARGUMENTS 的描述、留言、關聯 ticket。

接著起兩個子代理並行調查：
1. 第一個：在程式碼庫裡找出所有相關的既有實作、可複用的模組
2. 第二個：評估風險——這次變更會碰到哪些高流量路徑、有沒有測試覆蓋不足的地方

兩個代理都回來後，輸出：
- 實作步驟（依相依順序排好）
- 風險清單
- 建議的 commit 粒度

不要開始寫程式碼。

執行 /plan ENG-4213，一條指令就把整條流程跑完：拉 ticket → 並行調查程式碼庫 → 評估風險 → 彙整方案。使用者只要看結論，再決定要不要開工。

這就是 slash command 系列前三篇的完整弧線：定義可複用的提示詞（intro）→ 動態注入上下文（context）→ 編排工具和子代理（本篇）。走到這一步，.claude/commands/ 就不再是快捷鍵資料夾了，而是團隊共用的小型工作流庫。