每天开场那几句几乎一字不差："先看 git log 再动手""改完跑一下单测""顺手把 CHANGELOG 补上"。说一次是沟通，说一百次是浪费，而且每次措辞不同，产出也就不同。

斜杠命令解决的就是这件事：把一段固定流程写成一个文件，之后输入 / 加名字就够。

---

1. 内置命令：先认清手上有什么

命令	作用	什么时候用
/help	列出可用命令与用法	记不清命令名时先看它
/clear	清空当前上下文	换话题，旧上下文完全不需要了
/compact	压缩上下文	同一话题继续，但 token 快满了
/model	切换模型	简单任务换小模型，复杂推理换大模型
/config	打开配置界面	改主题、模型等常规项
/permissions	查看与管理权限规则	确认某条 deny/allow 是否生效
/memory	查看与编辑记忆文件	确认这次会话加载了哪些 CLAUDE.md
/init	生成初始 CLAUDE.md	新仓库第一次接入
/agents	管理子代理	查看有哪些 subagent 可委派
/mcp	管理 MCP server	确认外部工具是否连上
/status	查看会话状态	核对当前模型、账号、工作目录
/resume	恢复历史会话	接着昨天没做完的活
/exit、/quit	退出	——

内置命令集合随版本变化，以 /help 的实际输出为准，别看旧文章背。/clear 与 /compact 的差别值得单独记：前者是"忘掉"，后者是"揉碎再放进上下文"——换话题用 clear，同一个话题嫌长用 compact。

---

2. 自定义命令放在哪

位置	作用域	进 git	适合
.claude/commands/<name>.md	当前项目	是	团队共用的流程
~/.claude/commands/<name>.md	所有项目	否	个人习惯、跨仓库复用
.claude/commands/<dir>/<name>.md	项目	是	带命名空间，如 /review:pr
~/.claude/commands/<dir>/<name>.md	所有项目	否	个人的分组命令

mkdir -p .claude/commands/review .claude/commands/release
ls .claude/commands/

文件名就是命令名，扩展名必须是 .md。目录名变成命名空间前缀——review/pr.md 对应 /review:pr，这是避免命令名爆炸最省事的办法。

---

3. 文件格式：frontmatter + 模板

命令文件是"YAML 头 + 提示词模板"，模板就是你要说的话，只不过写一次：

---
description: 按团队规范审一遍当前改动
argument-hint: <branch-or-path>
allowed-tools: Read, Grep, Bash(git diff:*)
model: MODEL_ID
---

审查范围：$ARGUMENTS

步骤：
1. `git diff --stat` 看改动面，超过 400 行的文件单独列出来
2. 逐文件检查：命名、错误处理、日志、边界条件
3. 输出格式：按严重程度分组的清单，每条给"文件:行 + 问题 + 改法"
4. 最后一行写"结论：可合并 / 需修改 / 需讨论"

frontmatter 字段	作用	不写的后果
description	在命令列表里显示用途	只剩文件名，别人不敢用
argument-hint	提示参数怎么写	用户不知道要不要带参数
allowed-tools	限定这次可用的工具	沿用当前会话权限
model	指定模型	用会话默认模型
其他字段	如禁用模型自动调用一类	按当前版本核对字段名

字段名与取值各版本有增删，配之前按当前版本核对，写错的字段会被忽略而不是报错。

---

4. 参数占位：把命令变成"可调用函数"

写法	含义	例子
$ARGUMENTS	全部参数原文	/review 123 → 123
$1 $2 $3	位置参数	/fix 123 fast → 123、fast
@path/to/file	引用文件，内容进上下文	@docs/api-style.md
!`cmd`	执行命令，把输出注入	!`git diff --stat`

--- 
description: 给指定 PR 做一次自审
argument-hint: <pr-number> [focus-area]
---
PR 号：$1；关注点（可选）：$2

先跑：!`git log --oneline -15`
再看：@docs/review-checklist.md

如果 $2 为空，按"正确性 → 可维护性 → 性能"顺序全覆盖。

位置参数的最大价值是让模板不必依赖猜。写清"$2 为空时怎么办"，比让模型自行判断稳得多。

---

5. 命令里引用文件与跑命令的注意点

@ 与 ! 都很有用，也都有代价：

参考规范：@docs/api-style.md
当前改动：!`git diff --stat`

• @ 会把文件读进上下文。引用一份 2000 行的规范，等于开局就烧掉大半预算。只引用真正需要的段落，或者把规范拆成小文件。
• ! 在本地真实执行。命令要快、要幂等、不能有副作用——git status 没问题，npm install 会让每次调用都等一分钟。
• ! 的输出会进上下文，git log 不带参数在大型仓库里能刷出几千行，用 -n 限制条数。

这两条合起来是一句：命令模板的每个字符都在花预算，引用等于加倍花。

---

6. 命令、skill、subagent 怎么分工

维度	斜杠命令	skill	subagent
触发方式	用户显式输入 /名字	按描述匹配，或显式调用	主流程委派
上下文	与主会话共用	加载进主会话	独立上下文
适合	固定流程模板	领域知识 + 方法	独立子任务、脏活、防止污染
典型例子	/review、/release:changelog	某类系统的排查方法论	"把这个模块的测试补齐"
分发方式	一个 .md 文件	一个目录 + SKILL.md	一个 .md 文件
复用粒度	单次流程	跨任务的知识	跨任务的工作单元

判断方法很直接：

• 你每次都要说同一段话 → 命令；
• 你希望模型在合适时机自己想起某套方法 → skill；
• 这件事会读一大堆文件、产出很长，不想污染主上下文 → subagent。

三者可以组合：一个命令里写"委派 subagent 去做 X"，模板负责流程，subagent 负责隔离。

---

7. 团队共享：按任务域分目录

.claude/commands/
├── review/
│   ├── pr.md
│   └── security.md
├── release/
│   ├── changelog.md
│   └── tag.md
├── db/
│   └── migration.md
└── test/
    └── coverage.md

命名三条习惯：

1. 动词 + 对象：review:pr 比 pr-thing 清楚，release:changelog 比 changelog2 清楚；
2. 小写短横线，不用空格、中文、大小写混排——命令名是要手打的；
3. 一个命令只做一件事，需要串联就在命令里写"下一步调用 /release:tag"。

团队落地时，命令文件和代码一样要 review：description 写清楚、模板里不写死个人路径、不引用只有你有权访问的文件。

---

8. 排错：六个高频坑

现象	原因	处理
/ 列表里没有新命令	放错目录、扩展名不是 .md、frontmatter 语法错	对照第 2 节的位置表；--- 必须顶格闭合
输入命令后提示找不到	与内置命令同名被遮蔽，或命名空间写错	换名；目录名与输入的前缀要一致
模板里的路径找不到	用了相对路径，基准是 cwd 不是仓库根	用仓库相对路径，必要时在模板里先 pwd 确认
命令跑完质量很差	模板太长，关键步骤被稀释	拆成两三条命令，每条只做一件事
参数没生效	用了 $ARGUMENTS 但用户没传；或 $1 与 $2 顺序写反	加 argument-hint，并在模板里写"为空时怎么办"
frontmatter 报错/被忽略	YAML 里值含冒号未加引号，如 description: 审查: PR	加引号；改完在 / 列表里确认出现

第 4 条容易被低估：命令不是越长越强。一份 80 行的模板，模型很可能只遵守了前 10 行。命令的最佳长度是"刚好写完流程，没有背景介绍"。

---

9. 边界：什么时候别写命令

需求	更合适的做法	理由
一次性任务	直接在对话里说	写成文件还要维护
需要独立上下文的探索	subagent	命令与主上下文共用，会互相污染
领域知识与方法论	skill	需要"按需加载"而不是"每次全量"
必须每次都执行的检查	CI / hook	命令要靠人记得输入
长文档参考	引用具体小节	整篇塞进模板等于浪费预算
需要参数的复杂编排	命令 + subagent 组合	单靠模板难以控制分支

---

10. 自测

1. /clear 与 /compact 分别在什么场景下用？
2. review/pr.md 对应哪条命令，命名空间是怎么形成的？
3. $ARGUMENTS 与 $1 的差别是什么，什么情况下必须用后者？
4. 模板里 @docs/x.md 与 !`cat docs/x.md` 有什么实质区别？
5. 一段流程该做成命令、skill 还是 subagent，判断依据有哪三条？
6. 命令模板写到 80 行后效果反而变差，原因是什么，怎么改？