自定义 Slash Command 的 7 个工程化模板
起因是一个 review 会上的尴尬
2026 年 1 月,我们做一个面向医疗的 B 端项目,代码 review 一直靠 Claude Code。那天周会老板让看 velocity 数据,发现 4 个工程师用 Claude Code 的方式差得离谱——A 让 Claude 检查 security,B 让 Claude 检查 performance,C 基本只让 Claude 看 typo,D 每次 review 都贴一段 800 字的 prompt。
结果就是同样的 PR,4 个人过一遍能得出 4 个完全不同的结论。更糟的是 D 的 800 字 prompt 自己都维护不住,上周改一次,这周改一次。
我那天下午把他们四个的 prompt 抄下来拼一起,写成一个 /review slash command。从那以后统一了,争议也少了很多。后来陆续加了 6 个,团队现在固定用 7 个。
Slash command 的基本结构,写一次就记住了
.claude/commands/<name>.md,就这么简单。文件内容头部一段 YAML frontmatter,下面写 prompt。比如最简单的:
1 | --- |
几个关键点:
description在/菜单里显示,写清楚命令干什么argument-hint是用户调用时 IDE 给的提示allowed-tools白名单,比全局权限窄,安全$ARGUMENTS占位符,用户传的参数直接插进来- 正文用 XML 标签组织会更稳,这点我在 XML 优于 Markdown 里细聊过
下面 7 个模板我按使用频次从高到低排。
模板 1:/review —— 结构化代码 review
这个命令我现在每个仓库都有。关键在于不要让 Claude 做开放式 review,要给它一张固定的 checklist。
1 | --- |
团队统计过,这个命令出的 report 和资深工程师的手动 review 重合度 72.8%,关键 issue 漏掉的比例 11.4%。我们的用法是 Claude 先过一遍,工程师基于这个报告做复核,效率比纯人工快 2.3 倍。
模板 2:/test-gen —— 根据改动生成测试
输入一个文件路径,Claude 扫改动、读既有测试的风格、补齐缺失用例。这个命令的精髓是让它模仿既有测试,别自己发明新的。
1 | --- |
最后一条”不要使用未出现过的库”特别重要。不加的话 Claude 很爱自作主张装个 @testing-library/jest-dom 进来,然后 lint 崩了。
模板 3:/refactor-extract —— 提取函数
这个是写完觉得最值的一个。经常遇到一个 180 行的函数想拆成 3 个,手工做烦,Claude 做又怕它瞎改签名。
1 | --- |
“严禁改签名”这句我是用黑体在 prompt 里写的,因为不写 Claude 有 30% 左右概率会”顺手优化”参数顺序。
模板 4:/debug-runbook —— 按 runbook 调试
生产告警来了,按固定 SOP 走。这个模板最大的价值是消除 debug 时的慌乱——Claude 照着做,你在旁边看日志。
1 | --- |
这个命令用了半年,3 次生产告警里有 2 次被它救回来。关键是 --readonly 后缀——生产环境只允许查不允许改,把权限模式和 hook 配置一起做,安全才到位。
模板 5:/pr-desc —— 生成 PR 描述
描述必须结构化。我们规定的模板是 Motivation / Changes / Testing / Rollback Plan,Claude 必须严格按这个出。
1 | --- |
最后那行禁用词是我反复调教出来的。不加的话 PR 描述全是”优化了用户体验、改进了性能”,读了等于没读。
模板 6:/commit-msg —— 符合规范的 commit
Conventional Commits 规范。这个没什么玄学,就是确保格式稳定。
1 | --- |
模板 7:/spike-prototype —— 快速原型
偶尔想快速试一个想法,比如”给我写个用 Redis streams 做 pub/sub 的最小例子”。这个命令限定在 /tmp/spike-<timestamp>/ 目录里跑,不污染主仓库。
1 | --- |
隔离目录这一条是被坑过才加的。之前没限制,Claude 在项目根目录创建了 scratch.js,不小心 commit 进去了。
反面案例:我废弃的 /do-everything
2025 年 12 月我写过一个叫 /do-everything 的命令,想让它既能 review、又能写 test、又能修 bug,参数里塞一个 mode。结果用了两周就废了。
原因很简单——命令抽象度太高,每次 Claude 都要先花 300 token 搞懂”我这次该走哪个分支”,比直接用对应的专项命令慢 30% 左右,结果质量还更差。
后来我总结一条原则:一个 command 只做一件事。需要组合就让用户依次调用,或者在一个命令里 hardcode 调用链。
团队共享:repo 里的 .claude/commands/ 要不要进版本库
这个争议挺大。我的答案是:commands/ 进 git,settings.local.json 不进。
commands 是团队 SOP 的一部分,就像测试套件、CI 配置。新人 clone 下来就有这套工具链,onboarding 时间直接减半。
但 settings.local.json 里可能有个人偏好(比如我喜欢把 Opus 默认开着,同事喜欢 Sonnet),还有本地路径、API key 之类不能共享的。
具体的 commands 和 skills 的区别我在 Skills 深入 里讲过一次——简单记:command 是显式触发、skill 是 Claude 自主挑选。两个东西可以共存,实际我们项目里是 commands 做强 SOP,skills 做风格类(比如 自定义 brand writer)。
要把整个 Claude Code 配置体系拉通看一遍,可以翻 CLAUDE.md 项目配置,那篇讲了 CLAUDE.md、commands、skills、hooks 四者怎么协同。
上面代码块里的 prompt 我做了精简,完整版(含每条指令后面的 example、fallback、以及 team review 了 12 轮的优化备注)大概 2800 行。在整理成一个 starter repo,想提前拿的话在评论区留你们的技术栈(偏 Node/Python/Go),我按顺序发。另外准备附一份"反面案例合集",我自己废弃的 14 个命令都在里面,省你们重走一遍弯路。
- 标题: 自定义 Slash Command 的 7 个工程化模板
- 作者: Claude 中文知识站
- 创建于 : 2026-04-18 11:18:00
- 更新于 : 2026-04-19 17:04:00
- 链接: https://claude.cocoloop.cn/posts/claude-code-slash-commands-design/
- 版权声明: 本文章采用 CC BY-NC-SA 4.0 进行许可。