Slash Command 进阶：与子代理和工具协作

前两篇讲了 slash command 是什么（一个 Markdown 文件）和如何用 ! 前缀把 shell 输出注入上下文。这一篇讲的是更重的事：怎么让一条 command 编排 Claude Code 里最强的几个能力——文件引用、子代理、MCP 工具——并把权限管好。

写到这一层，command 不再只是"提示词快捷方式"，而是可复用的小型工作流。

`@file` 引用：比 `!cat` 更合适的静态注入

!cat file.md 能把文件内容塞进上下文，但它走的是 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、日志、测试结果）	✅ 必须 `!`	❌ 不能

规律：静态文件用 @，动态输出用 !，参数路径用 !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 里，后续对话就变慢变傻。

正确做法是把这种活交给 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：
- 需要改哪些文件
- 每一步是独立提交还是一起
- 有没有需要先跟 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 预算也会被一条 command 吃掉。

三件套的使用时机

写到这里，Claude Code 里给 command 注入"外部能力"的机制基本齐了。怎么选：

需求	首选机制
固定的规范、模板、上下文文档	`@file` 引用
实时状态（diff、日志、测试结果、数据库查询）	`!shell` 注入
参数化的文件内容	`!cat $ARGUMENTS`
耗 context 的调研、跨文件搜索	subagent via Task
外部系统（issue tracker、监控、生产数据）	MCP 工具 + `allowed-tools`
多步串行/并行工作流	父 command 调度 subagent

权限边界通过 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. 第二个：评估风险——这次改动会碰到哪些高流量代码路径、有没有测试覆盖缺口

两个代理都回来之后，输出：
- 实施步骤（按依赖顺序排好）
- 风险清单
- 建议的提交粒度

不要开始写代码。

触发 /plan ENG-4213，一条指令跑完：拉 ticket → 并行调研代码库 → 评估风险 → 汇总方案。用户要做的只是看结论再决定开工。

这就是 slash command 系列前三篇的完整弧线：定义可复用的提示词（intro）→ 动态注入上下文（context）→ 编排工具和子代理（本篇）。到这一层，.claude/commands/ 已经不是快捷方式了，是团队的小型工作流库。