自定义 Slash Command 的 7 个工程化模板

Claude 中文知识站 Lv4

起因是一个 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
2
3
4
5
6
7
8
9
10
11
---
description: 检查代码改动的安全性
argument-hint: "[文件路径或 PR 号]"
allowed-tools:
- Read
- Grep
- Bash(git diff:*)
- Bash(gh pr diff:*)
---

你是一个资深安全审计师。请对 $ARGUMENTS 指向的改动做安全 review...

几个关键点:

  • description/ 菜单里显示,写清楚命令干什么
  • argument-hint 是用户调用时 IDE 给的提示
  • allowed-tools 白名单,比全局权限窄,安全
  • $ARGUMENTS 占位符,用户传的参数直接插进来
  • 正文用 XML 标签组织会更稳,这点我在 XML 优于 Markdown 里细聊过

下面 7 个模板我按使用频次从高到低排。

模板 1:/review —— 结构化代码 review

这个命令我现在每个仓库都有。关键在于不要让 Claude 做开放式 review,要给它一张固定的 checklist。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
---
description: 多视角代码 review(安全/性能/可维护性)
argument-hint: "[PR 号 或 文件 glob]"
allowed-tools:
- Read
- Grep
- Glob
- Bash(git diff:*, gh pr:*)
---

对 $ARGUMENTS 做 review,严格按下面 4 个视角分别出结论。
每个视角最多 5 条发现,每条格式:
- 【严重级 高/中/低】
- 问题描述(不超过 30 字)
- 文件:行号
- 建议改法(代码片段,不超过 6 行)

<view name="安全">
关注 SQL 注入、XSS、SSRF、硬编码密钥、不安全反序列化...
</view>

<view name="性能">
关注 N+1 查询、未 index 的大表扫描、同步阻塞、内存泄漏...
</view>

<view name="可维护性">
关注命名、函数长度、魔法数字、重复代码、测试覆盖...
</view>

<view name="兼容性">
关注 API break、数据库 schema 迁移、依赖版本冲突...
</view>

最后给一个 <verdict>approve / request-changes / reject</verdict>

团队统计过,这个命令出的 report 和资深工程师的手动 review 重合度 72.8%,关键 issue 漏掉的比例 11.4%。我们的用法是 Claude 先过一遍,工程师基于这个报告做复核,效率比纯人工快 2.3 倍。

模板 2:/test-gen —— 根据改动生成测试

输入一个文件路径,Claude 扫改动、读既有测试的风格、补齐缺失用例。这个命令的精髓是让它模仿既有测试,别自己发明新的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
---
description: 为指定文件/函数生成单元测试
argument-hint: "[文件路径]"
allowed-tools:
- Read
- Grep
- Glob
- Edit
- Bash(npm test:*, pytest:*)
---

为 $ARGUMENTS 补齐测试。步骤:

1. 读取目标文件,列出所有 public 函数
2. 搜索项目现有测试文件(*test*, *spec*),挑 2-3 个最相似的
3. 严格模仿既有测试的:
- 测试框架和断言风格
- describe/it 命名规则
- mock 方式
- fixture 组织
4. 对每个未覆盖的函数生成:正常路径 1 个 + 边界情况 2 个 + 错误路径 1 个
5. 运行测试确认通过

不要使用任何项目中未出现过的断言库或测试 util。

最后一条”不要使用未出现过的库”特别重要。不加的话 Claude 很爱自作主张装个 @testing-library/jest-dom 进来,然后 lint 崩了。

模板 3:/refactor-extract —— 提取函数

这个是写完觉得最值的一个。经常遇到一个 180 行的函数想拆成 3 个,手工做烦,Claude 做又怕它瞎改签名。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
---
description: 从指定函数中提取子函数,保持对外接口不变
argument-hint: "[文件:函数名]"
allowed-tools:
- Read
- Edit
- Bash(npm test:*, pytest:*, cargo test:*)
---

对 $ARGUMENTS:

1. 先用 Read 读取目标函数完整代码
2. 找出 2-4 个逻辑独立的代码块(循环、分支、连续 I/O 操作等)
3. 每个块提取成一个 private 函数,命名动词+名词
4. **严禁改动原函数的签名、参数、返回值**
5. 提取完立刻跑测试,失败则回滚

最后给我一个 before/after 行数对比。

“严禁改签名”这句我是用黑体在 prompt 里写的,因为不写 Claude 有 30% 左右概率会”顺手优化”参数顺序。

模板 4:/debug-runbook —— 按 runbook 调试

生产告警来了,按固定 SOP 走。这个模板最大的价值是消除 debug 时的慌乱——Claude 照着做,你在旁边看日志。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
---
description: 按 runbook 调试生产问题
argument-hint: "[告警 ID 或问题描述]"
allowed-tools:
- Read
- Grep
- Bash(kubectl:*, docker logs:*, curl:*, psql:* --readonly)
---

问题:$ARGUMENTS

严格按以下 runbook 执行,每一步完成汇报结果后再进入下一步:

<step n="1">检查服务健康:kubectl get pods -n prod,列出 Not Ready 的</step>
<step n="2">拉最近 5 分钟 error 日志,grep 出 top 3 error pattern</step>
<step n="3">查数据库连接池使用率(SELECT ... FROM pg_stat_activity)</step>
<step n="4">查上游依赖 latency(curl /health/deps)</step>
<step n="5">对照 recent deploys(最近 2 小时 CI/CD 记录),判断是否 regression</step>
<step n="6">输出诊断结论:根因 + 紧急缓解动作 + 是否需要 rollback</step>

任何一步失败立即停止,不要跳步。

这个命令用了半年,3 次生产告警里有 2 次被它救回来。关键是 --readonly 后缀——生产环境只允许查不允许改,把权限模式和 hook 配置一起做,安全才到位。

模板 5:/pr-desc —— 生成 PR 描述

描述必须结构化。我们规定的模板是 Motivation / Changes / Testing / Rollback Plan,Claude 必须严格按这个出。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
---
description: 根据 git diff 生成 PR 描述
argument-hint: "[base 分支,默认 main]"
allowed-tools:
- Bash(git diff:*, git log:*)
---

对比 $ARGUMENTS(默认 main) 到当前分支,生成 PR 描述:

## Motivation
用一段话说清楚为什么要做这个改动。不要从 diff 倒推,要从 commit message 的语气中推测业务目的。

## Changes
按模块分组的 bullet list。一项不超过 15 字。

## Testing
- 自动化测试:新增/修改了哪些测试
- 手动验证:列出复现步骤

## Rollback Plan
一句话说清楚怎么回滚。如果有 DB 迁移,必须写 down script。

禁止使用"优化"、"改进"、"增强"这种模糊词。

最后那行禁用词是我反复调教出来的。不加的话 PR 描述全是”优化了用户体验、改进了性能”,读了等于没读。

模板 6:/commit-msg —— 符合规范的 commit

Conventional Commits 规范。这个没什么玄学,就是确保格式稳定。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
description: 生成 conventional commits 格式提交信息
allowed-tools:
- Bash(git diff --cached:*, git status:*)
---

检查 staged 改动,生成一条 commit message:

格式:<type>(<scope>): <subject>

type 从 feat/fix/refactor/docs/test/chore/perf 中选。
scope 是模块名,从文件路径推断。
subject 祈使句,不超过 50 字符,不加句号。

如果 staged 超过 8 个文件且涉及多个 scope,先提醒我"改动太杂,建议拆分",然后给出一个折中的 scope。

Body 可选。如果有破坏性改动必须写 BREAKING CHANGE 段。

模板 7:/spike-prototype —— 快速原型

偶尔想快速试一个想法,比如”给我写个用 Redis streams 做 pub/sub 的最小例子”。这个命令限定在 /tmp/spike-<timestamp>/ 目录里跑,不污染主仓库。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
---
description: 在隔离目录快速写一个原型
argument-hint: "[想验证的技术点]"
allowed-tools:
- Write
- Edit
- Bash(mkdir:*, cd:*, npm init:*, python -m venv:*, node:*, python:*)
---

在 /tmp/spike-$(date +%s)/ 创建一个最小可运行原型验证 $ARGUMENTS。

要求:
- 单文件优先,超过 150 行再拆
- 依赖最少,能用标准库就别装包
- 必须可以 node/python 直接跑出结果
- 结束时把运行命令和输出一起贴给我

不要在主仓库目录下创建任何文件。

隔离目录这一条是被坑过才加的。之前没限制,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 四者怎么协同。

这 7 个模板的完整版
上面代码块里的 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 进行许可。
评论