目录概要

1. 接着上一篇的尾巴
2. 一段 80 行 markdown 是怎么变成 Claude 行为的
3. Frontmatter 13 字段全景：能开关什么
4. 三种动态内容注入：!、@、$ARGUMENTS
5. paths 字段：把 command 钉在文件类型上
6. context: fork——让 command 在隔离上下文里跑
7. 官方 65 个命令的分布与分级
8. 必须背下来的 10 个命令
9. 写自己的 command 的三种典型形态
10. 容易搞错的几个细节

1. 接着上一篇的尾巴

上一篇我们把 release-notes 生成器拆解完毕，结尾留下一句“下一篇把 Commands 单独拎出来细讲”——今天这篇就来兑现这个承诺。

但在正式开始之前，得先解释一件事：为什么 Command 这个看似“简单”的功能，值得单独用一整篇文章来剖析？

原因在于，当你真正用它来搭建工作流时，会发现 Command 有一半的能力都藏在它如何把外部世界拼接进提示词这件事上：

• !shell-command`` 将命令输出注入进来
• @filepath 把文件内容注入进来
• $ARGUMENTS 将用户参数拼接进来
• paths 让它只对特定文件类型生效
• context: fork 让它去开辟子上下文

这些字段每一个单独看都不复杂，但组合起来，却能让 Command 从一个单纯的“按钮”进化为“参数化的工作流模板”。这正是上一篇没有展开详述的部分。

资深架构师看待 Command，视角应该跟看待 Makefile target 或者带 frontmatter 的 shell script 一样——它是一种 declarative pipeline 的入口描述符，而不仅仅是一段聊天提示。这一篇，我们就按这个视角来逐步拆解。

2. 一段 80 行 markdown 是怎么变成 Claude 行为的

我们先画出 Command 的执行链路。理解了这条链路，再看各个字段时，每个字段在哪一步起作用就一目了然了。

sequenceDiagram
actor User as 用户
participant CLI as claude CLI
participant Loader as Command Loader
participant Tools as 内置工具
(Bash/Read/...)
participant Model as Claude 模型
participant Tool2 as 模型调度的工具
User->>CLI: 输入 /release-notes-crafter
CLI->>Loader: 解析 / 触发
Loader->>Loader: 1. 读 .claude/commands/release-notes-crafter.md
Loader->>Loader: 2. 解析 frontmatter
Loader->>Tools: 3. 执行 ! 块 (shell)
Tools-->>Loader: stdout 结果
Loader->>Loader: 4. 内联 @ 文件引用
Loader->>Loader: 5. 替换 $ARGUMENTS / $0..$N
Loader->>Model: 拼好的最终 prompt + frontmatter (model/effort/allowed-tools)
Model->>Tool2: 按 prompt 指示调用 AskUserQuestion / Agent / Skill
Tool2-->>Model: 工具结果
Model-->>User: 最终响应

这条链路里有四个关键的时机，需要区分清楚：

这里有一个很多人不知道的关键规则：! 块是在 Loader 阶段由本机执行的，$ARGUMENTS 也是在这里被替换的。这意味着，模型看到的现场信息，是已经由 Loader “预处理”过的。而模型自己再去调用 Bash() 拿到的东西，在输出格式或环境上可能就跟 Loader 直接灌进来的不一样。

打个比方，如果你在 command 里用 !`git log` 拿到了带颜色的日志，然后模型再自己跑 Bash("git log")，它拿到的可能是纯文本。这个差异在某些场景下（比如解析输出）会直接导致结果出错。很多人在编写多个 command 后，都会在某个莫名其妙的 bug 里撞上这个点，才真正意识到“原来 Loader 和模型不是同一个执行者”。

3. Frontmatter 13 字段全景：能开关什么

在最新版（v2.1.96）中，Command 的 frontmatter 共有 13 个字段。一个完整的 YAML 示意如下：

---
name: my-command # 显示名 + /slash 标识，缺省取目录/文件名
description: 做某件有用的事 # 自动补全 + 语义匹配（如果允许）
argument-hint: [issue-number] # 自动补全时的参数 placeholder
disable-model-invocation: false # 是否禁止模型自动触发
user-invocable: true # 是否在 / 菜单出现
paths: "src/**/*.ts" # glob，命中文件才激活（可逗号分隔或列表）
allowed-tools: Read, Edit, Bash(gh *) # 激活时不需要权限确认的工具
model: sonnet # 运行时模型
effort: high # 运行时 effort 等级
context: fork # 设为 fork 则跑在独立子上下文
agent: general-purpose # context: fork 时的子 agent 类型
shell: bash # !`cmd` 块用什么 shell（bash/powershell）
hooks: # 仅作用于本 command 的 lifecycle hooks
  PostToolUse:
    - matcher: "Edit"
      hooks: [...]
---

这 13 个字段不是平铺的，按“控制什么”可以分成五类：

root((Command 13 字段))
  身份
    name
    description
    argument-hint
  可见性与触发
    user-invocable
    disable-model-invocation
    paths
  运行时资源
    model
    effort
    allowed-tools
  上下文边界
    context
    agent
  动态行为
    shell
    hooks

下面挑几个容易踩雷的单独说。

3.1 name 缺省、显式哪个对？

name 缺省时会取目录或文件名。比如 .claude/commands/release-notes-crafter.md 没写 name，slash 自动就是 /release-notes-crafter。正常情况下省着写就好，只有在 plugin marketplace 命名冲突，或中文目录名撞到 unicode 时才需要显式覆盖。

真正不可省的字段是 description——它直接影响自动补全是否展示，以及模型是否能匹配到。

3.2 description 决定生死

---
description: 提交并 push 当前分支，再开 PR
---

description 是用户在 / 菜单里看到的一行字，也是模型进行语义匹配（如果 disable-model-invocation 没关）的依据。没写 description 的 command 实际上是“半盲”状态——用户能通过 /name 触发，但永远不会被自动建议。

写法上有两个常见的反模式：

一个折中的写法是：一个动词 + 一个目标 + 一个约束。例如“提交并 push 当前分支并开 PR”——动词“提交+push+开”，目标“PR”，约束“当前分支”，清晰明了。

3.3 disable-model-invocation：把按钮锁死成“只能手按”

默认情况下，Command 的 description 会进入模型的可调用列表。但 Command 的设计哲学本身就是“用户主动触发的入口”。因此，很多团队会把所有 commands 默认设置 disable-model-invocation: true：

---
description: 提交并开 PR
disable-model-invocation: true
---

它的效果是：

• 用户输入 /commit-and-pr，正常触发。
• 用户说“帮我提交并开 PR”，模型不会主动选这个 command（它会自己用 Bash + gh 去做）。

这个开关跟 user-invocable: false 是一对镜像：

这四个象限互不矛盾，根据需求选择即可。

3.4 allowed-tools：本地小作用域的权限控制

allowed-tools: Read, Edit, Bash(gh *)

这里列出的工具，在该 command 激活期间不会触发权限确认。语法支持精确到子命令：

• Bash(gh *)：只放行 gh 开头的 bash 命令
• Bash(npm test)：只放行字面 npm test
• Bash：所有 Bash（最宽，少用）
• Read、Edit、Write：纯工具名

需要注意，allowed-tools 是叠加在全局 settings 之上的本地白名单。它不会扩展全局 deny 规则——deny 永远是最高优先级。

3.5 model 和 effort：分层用模型省钱

上一篇讲过 release-notes-crafter 用 model: haiku 是因为 command 只编排不算账。这里再补充一点：

---
description: 起草 release notes 草稿
model: opus
effort: high
---

某些写作类 command 则反过来——内容质量重要，那就让 opus 以高 effort 上。 effort 等级 low/medium/high/max 之间是 token 消耗倍数关系（max 大概是 low 的 8x），所以默认值不写就好，只在特殊场景才显式拉满。

4. 三种动态内容注入：!、@、$ARGUMENTS

这是 Command 区别于“普通提示词”的核心所在。三种注入分别处理“shell 输出、文件内容、用户参数”。

4.1 !shell-command`` —— shell 输出注入

---
description: 提交工作流——基于当前 diff 生成 commit message
allowed-tools: Bash(git *), Read, Edit
---
# 提交工作流

## 当前 git status
!`git status --short`

## 暂存区 diff
!`git diff --staged`

## 最近 5 次提交
!`git log --oneline -5`

请基于以上信息：
1. 写一条 conventional commits 风格的 commit message
2. 展示给我确认
3. 确认后执行 git commit

加载这个 command 时，三个 ! 块会被先执行，stdout 替换原位置，再把整段内容塞给模型。模型看到的是已经填好的现场，省了它再去 Bash 一遍。

这里有几个要点：

• 反引号是 backtick，不是单引号。这个问题在 markdown 编辑器里很常见，很容易被自动替换。
• ! 块里只能跑一行，多行需要用 && 连接。
• 如果命令报错，stderr 也会被带进来——这一点可以用来辅助调试。
• shell: powershell 时，语法会变成 PowerShell 表达式。
• ! 块的输出不计入 allowed-tools 检查，因为它是在 Loader 阶段执行的。

一个常见的错误是把交互式命令放进去，比如 !`vim file.md`，这会让 Loader 卡住。Loader 期望的是一个“跑完即返回 stdout”的一次性命令。

4.2 @filepath —— 文件内容注入

---
description: 根据规范 review 当前 PR
---

请按照以下规范检查暂存改动：
@docs/CODE_REVIEW_CHECKLIST.md

当前改动：
!`git diff origin/main`

@ 在 Loader 阶段把文件逐字内联进 prompt——它不是让模型去 Read，而是预先填好。

高级工程师立刻会关心的几件事：

• 大文件会爆 context 吗？ 会。@ 不截断、不压缩、不做 summary，100KB 的规范会原样塞进来，token 全计费。大文件更适合让模型自己去 Read——它读到一半发现不相关会自己退出；@ 更适合 <10KB 的稳定规范文件。
• 路径怎么解析？ 相对路径基准是当前工作目录（CWD），不是 command 文件自己的位置。这一点与 CLAUDE.md 的 @import 语义一致，很多人会记错。
• 跟 Read 比真正省了什么？ 不是 token（进了 prompt 都要算），是那一轮 tool call 的延迟，以及“模型先读再决定怎么用”这层认知步骤。对于每次都要读、且都按同样方式理解的规范类文件，直接 @ 内联，模型的注意力从第一个 token 起就落在规范上。
• 能不能用通配符？ 单个 @ 只接受一个路径。想拉多个文件就写多条 @ 行；想动态展开，就走 !`cat src/**/*.ts` 之类的 shell 路径。

到这里，@ 和 ! 的分工就清晰了：规范用 @（稳定、反复引用），现场用 !（动态、每次不同）。

4.3 $ARGUMENTS 和 $0..$N —— 参数

最后一种是用户传参。

---
description: 详细 review 一个 PR
argument-hint:  [reviewer]
---

# Review PR #$0
主审人：$1
详情：
!`gh pr view $0 --json title,body,files`
按以上规范展开 review，并把发现 @ 给 $1。

调用：

> /pr-review 1234 alice

替换规则：

4.4 三者组合的威力

把三种注入叠起来，一个 command 就能做到：

graph LR
    U[用户 /pr-review 1234] --> L[Loader]
    L -->|"$0=1234"| P1[替换参数]
    L -->|"!`gh pr view 1234`"| P2[拉 PR 元信息]
    L -->|"@CHECKLIST.md"| P3[内联规范]
    P1 --> M[最终 prompt]
    P2 --> M
    P3 --> M
    M --> Claude[模型执行 review]
    style L fill:#ff9
    style M fill:#afa

这正是 Command 不只是“按钮”的原因——它是一个会自己去抓现场的按钮。就像 Makefile 比“双击 .sh 脚本”的优势，在于 $(shell ...) 这种东西。Command 的 !/@/$ARGUMENTS 也是同样的道理。

5. paths 字段：把 command 钉在文件类型上

paths 是个低调但很有用的字段：

---
description: 检查 React 组件的 a11y
paths:
- "src/components/**/*.tsx"
- "src/pages/**/*.tsx"
---

它的效果是：当当前对话的焦点文件匹配 paths 时，这个 command 才进入 Claude 的可用列表。其他时候，它就是隐形的。

它与 disable-model-invocation 的区别在于：

• disable-model-invocation: true —— 永远不让模型自动选。
• paths: "..." —— 只在工作上下文相关时才作为候选。

paths 模式允许你为一个仓库写几十个超细分的 command，而不会污染补全。React 组件场景下才出现 React 相关的 command，写 SQL 时它们就自动隐身。它与 Skill 的 paths 字段是同一回事，共享同一套 glob 匹配引擎。

6. context: fork——让 command 在隔离上下文里跑

最后一个值得展开的字段是 context: fork：

---
description: 跨整个 monorepo 找出所有未使用的依赖
context: fork
agent: general-purpose
allowed-tools: Read, Glob, Grep, Bash(npm *)
---

# 找出未使用依赖
1. 找所有 package.json
2. 对比每个的 dependencies 和 src 引用
3. 列出未引用的依赖

加上 context: fork 之后，这个 command 不再“内联到主对话”——它跑在一个临时子上下文里，主对话只看到最终结果。

graph TB
    subgraph Main[主对话]
        M1[用户消息]
        M2[Claude 响应]
        Trig[/find-unused-deps 触发]
        R[只看到最终结果
'5 个未使用依赖：A B C D E']
    end
    subgraph Forked[fork 出的临时上下文]
        F1[读 100 个 package.json]
        F2[grep src 引用]
        F3[计算差集]
    end
    Trig -.fork.-> Forked
    Forked -.返回结果.-> R
    style Forked fill:#fcc
    style R fill:#cfc

这就把 Command 升级成了“带 UI 的 Subagent 入口”——用户主动触发，行为却像个 agent。

什么时候用？凡是这个 command 内部需要读大量文件、做大量推理、产生大量中间输出的场景：

• monorepo 全局扫描
• 跨整个仓库的统计
• 跑一遍所有测试并归类失败原因

不用 context: fork 的话，几百个文件读下来，会直接撑爆主对话的上下文。

7. 官方 65 个命令的分布与分级

讲完自定义 command，我们来看看“官方已经准备好的”。Claude Code v2.1.96 内置了 65 个 slash command，按功能聚类：

root((65 个内置 10 大类))
  上下文管理 最值钱
    /context
    /compact
    /clear
  模型控制
    /plan
    /model
    /effort
  会话管理
    /rename
    /resume
    /rewind
    /btw
  扩展管理
    /agents
    /skills
    /mcp
    /memory
  调试兜底
    /doctor
    /diff
  其他 5 类 一年两次
    认证 / 配置
    项目 / 远程 / 导出

65 个全记得完吗？记不完，也不需要。其中 5 个分类（认证、配置、项目管理、远程、导出）一年用不上两次。完整清单可以查官方的 Slash Commands 文档。下面只挑架构师工作流里影响最大的 5 个分类详细说，也就是上面 mindmap 上半截那五支。

7.1 上下文管理类——最值钱的 7 个

/compact 的 instructions 参数被严重低估了。举个例子：

/compact 保留所有对架构决策的讨论，删除工具输出

压缩后剩下的就是决策脉络，工具反复读文件的 token 全没了。在长对话里，这一招经常能救命。

7.2 模型控制——架构师最该熟的几个

复杂任务有一个标准流程：/plan 进 plan mode → 跟 Claude 来回打磨方案 → 满意了退出 plan mode → 开干。这个流程可以避免 Claude “上来就动手”造成的浪费。

7.3 会话管理——多线程开发利器

/rewind 是 Claude Code 比传统 IDE 更强的地方——不仅会话能回退，代码也能回到那一刻。Claude 跑偏了，不要修修补补，直接 rewind 到岔路口重选方向，比一行行 revert 干净得多。

7.4 扩展类——管你写的所有东西

后面的 06、07、08、10 篇会分别深入这些，这里只是认个门牌号。

8. 必须背下来的 10 个命令

如果只能记 10 个，按重要度排序如下：

这 10 个里，有 7 个是上下文/会话/模型管理类的——这不是巧合。LLM agent 工具的瓶颈从来不在能力，而在上下文管理。有十年传统软件经验的人，上来用 Claude Code，最容易踩的坑就是把它当成“无限上下文的助手”，不停地喂它信息——结果越用越笨，token 越烧越多。这 10 个命令里，7 个是治这个病的。

9. 写自己的 command 的三种典型形态

最后回到实战。Command 在实际项目里通常长成三种形态：

形态一：纯模板型（最简单）

---
description: 把 React 组件改成 hooks 写法
---
把当前选中的 React 组件从 class 写法改成 functional + hooks。
保持 props 接口、保持测试通过、保持 PropTypes。

零字段，纯 prompt。适合重复出现的“按规范做某件事”。

形态二：工作流编排型（最常见）

上一篇的 release-notes-crafter.md 就是这种：

---
description: Craft release notes for a given version — fetches commits between tags, categorizes them, writes a polished RELEASE_NOTES.md
model: haiku
---

正文用结构化 markdown 描述 step by step：哪步用 AskUserQuestion、哪步 Agent、哪步 Skill。Command 自己不干活，调度其他扩展。

形态三：现场快照型（带 ! 和 @）

---
description: 提交并 PR
allowed-tools: Bash(git *), Bash(gh *)
---

# 当前现场
!`git status --short`

# 暂存改动
!`git diff --staged`

# 项目 commit 规范
@docs/COMMIT_CONVENTIONS.md

请基于现场和规范，生成 commit message 并提交，然后 gh pr create。

把“上下文准备”自动化掉，模型一来就有完整快照。

写第一个 command 时，大家通常从形态一开始（容易），但真正起作用的 command 大多是形态二和形态三。

10. 容易搞错的几个细节

最后列几条踩过的坑，专挑文档里没强调的：

Backtick 不是单引号

!`git status` 用的是反引号（U+0060），不是单引号（U+0027）。VS Code 默认的 markdown 智能引号会把它偷换成 curly quote，结果命令不执行、没有报错，Loader 直接把那一行当成纯文本塞给模型。这个设计实在不够友好——连个 warning 都没有。

$ARGUMENTS 不会做 shell escape

如果用户传入的参数里有 ; | &，原样替换进 ! 块就是命令注入。永远不要把 $ARGUMENTS 直接拼到 ! 块里，要用就拼到自然语言提示里，让模型决定怎么用。

paths 是匹配“工作焦点”，不是匹配“会话历史”

测试 paths 是否生效：用 /add-dir 加目录，让你的 command 出现在补全里。只是打开一个 tab 不算“工作焦点”。

context: fork 不能套娃

fork 出的子上下文里，子 agent 不能再启动一个 fork。设计上是有意为之——为了避免无限递归。

hooks 字段的 matcher 是工具名，不是字符串

hooks:
  PostToolUse:
    - matcher: "Edit"    # 正确：匹配 Edit 工具
    - matcher: "edit*"  # 错误：不会匹配

完整的 matcher 语法，留到第 07 篇 hooks 系统里再展开。

写到这里

Command 这个看起来最朴素的扩展点，背后其实有一整套“prompt 编译期”——! 跑 shell、@ 内联文件、$ARGUMENTS 拼参数、paths 限定激活范围、context: fork 切换执行模式。这些字段的组合，让一个 markdown 文件变成了一个会自动抓取现场的工作流入口。

13 个 frontmatter 字段、3 种动态注入语法、65 个内置 command——这些细节背下来意义不大，真正有用的是知道哪个能力对应哪个字段。下次想“我要让一个 command 在 .ts 文件里才出现”，能立刻定位到 paths，就够了。

Skills 是这趟旅程的下一站。Command 是按钮，按下去执行；Skill 是工具箱里的工具，模型自己判断什么时候开柜子拿哪一把。下一篇，我们把 Skill 的 9 种类型、渐进式揭露的设计哲学，以及 Skill 工具的调用机制全部摊开讲。

Footnotes

外部链接

• Claude Code Slash Commands 官方文档
• Interactive Mode 文档
• Claude Code CHANGELOG