Claude Code 自定义命令与 Hooks:把重复操作变成一条命令
用 Claude Code 一段时间后,很多人都会撞上同一种烦:每天重复敲同一段长提示词——“review 这个 PR,注意并发、边界条件和错误处理,输出表格”;每次改完代码都要再补一句"跑一下 lint 和测试";每隔几天还要提防它手滑改了 .env 或者执行了 rm -rf。
这些事都不难,但每次都靠人记、靠嘴说,就一定会漏。Claude Code 其实给了两套机制来解决:自定义斜杠命令负责"把重复的提示词存起来",Hooks 负责"把必须执行的规则钉死"。前者省打字,后者兜底线。
一、自定义斜杠命令:提示词存成文件,随叫随到
自定义命令的本质很简单:一段提示词,存成一个 Markdown 文件,文件名就是命令名。
放在哪,决定谁能用
两个位置:
| 位置 | 生效范围 | 是否进 git |
|---|---|---|
| ~/.claude/commands/ | 本机所有项目 | 不进 |
| <项目根目录>/.claude/commands/ | 当前项目 | 提交后团队共享 |
比如在 ~/.claude/commands/review-pr.md 里写一段审 PR 的提示词,之后在任何项目里敲 /review-pr,那段提示词就会原样作为下一轮输入执行。子目录会变成命名空间:.claude/commands/frontend/component.md 对应 /frontend:component。
一个命令文件长什么样
文件分两部分:顶部的 YAML frontmatter(用 — 包起来)是配置,正文是指令。
---
description: 审查 PR 的代码质量、并发与边界条件
argument-hint: [PR 编号]
allowed-tools: Read, Grep, Bash(gh *)
---
审查 PR #$ARGUMENTS,重点看三点:
1. 并发与竞态:共享状态有没有锁或串行化保护
2. 边界条件:空值、空数组、超大输入怎么处理
3. 错误处理:失败时有没有重试、回滚和日志
输出一张表:问题 | 位置 | 严重程度 | 建议改法。只读代码,不要改任何文件。
四个 frontmatter 字段的含义:
- description:显示在 / 菜单里的说明,也帮助模型判断什么时候该自动调用这个命令。不写就默认取正文第一行。
- argument-hint:补全时显示的参数提示,比如 [PR 编号],提醒你该传什么。
- allowed-tools:这条命令执行期间,模型可以直接用的工具,不用再逐个弹窗确认。上面例子里的 Bash(gh *) 表示只放行 gh 开头的命令,不是放行所有 shell 命令。
- model:这次调用强制换模型,比如审代码强制用最强的模型,平时默认用快的。disable-model-invocation: true 则是反过来:禁止模型自己调用这条命令,只许人手动敲,适合带副作用的操作。
让命令带参数:四种动态语法
命令的正文不是死文本,四种写法能把它变成模板:
- $ARGUMENTS:命令名后面跟的全部内容。/fix-issue 123 紧急,$ARGUMENTS 就是 123 紧急。
- $0、$1:按位置取参数。同样是 /fix-issue 123 紧急,$0 是 123,$1 是 紧急。
- ! 开头:在命令执行前先跑一段 shell,把输出贴进提示词。写 !git log --oneline -10,最近 10 条提交记录就会自动出现在上下文里,不用你手动复制。
- @ 引用文件:@src/auth.ts 会把这个文件的内容直接带进来。
三个可以直接抄的命令
- /commit:按规范提交
---
description: 按约定式提交规范生成提交信息并提交
argument-hint: [提交说明]
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*)
---
先跑 git status 和 git diff 看改动,然后按约定式提交规范(feat/fix/docs/refactor)生成提交信息:$ARGUMENTS。提交前把信息先给我看一眼,确认后再执行。
注意 allowed-tools 的写法:Bash(git add:*) 这种带冒号通配符的格式,只放行指定前缀的命令。写成光秃秃的 Bash 等于把整个 shell 交出去,别这么干。
- /review-pr:审 PR 用固定检查单
见上一节的例子。关键是把检查单写死在文件里:并发、边界、错误处理三条每次都查,而不是每次临场发挥、这次想起并发、下次忘了边界。
- /changelog:从提交记录生成更新日志
---
description: 从最近提交生成更新日志
argument-hint: [版本号]
allowed-tools: Bash(git log:*)
---
最近提交记录:
!git log --oneline -20
按 feat/fix/docs 分类,生成 $ARGUMENTS 版本的更新日志。只写用户能感知到的变化,内部重构一句话带过。
!git log 这一行会在命令运行时先执行,输出自动贴进来——你不用再手动 git log 复制粘贴。
两个容易踩的坑
第一,allowed-tools 的授权只在命令执行的当轮有效,下一条你自己发的消息就失效了。这是故意的:授权跟着命令走,不会悄悄扩大成永久放行。
第二,2026 年的版本里,自定义命令已经并入 skills 体系:.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 会生成同一个 /deploy,行为一样。旧的 commands 文件继续能用,新写的东西可以优先按 skill 的格式写,两种写法现在是同一套机制。
二、Hooks:不靠模型的记性,靠机制保证
自定义命令解决的是"你懒得重复说",Hooks 解决的是"你说了它也可能忘"。Hook 是绑在会话生命周期事件上的 shell 命令,触发点一到就自动跑,不经过模型同意。
配置放在哪
Hook 写在 settings.json 的 hooks 字段里,三个位置对应三个作用域,和命令一样:
- ~/.claude/settings.json:本机所有项目。
- .claude/settings.json:当前项目,提交进 git,全团队生效。
- .claude/settings.local.json:当前项目、仅自己,不提交。
也可以在 Claude Code 里敲 /hooks,用向导查看和管理已配置的 Hook,不用手改 JSON。
事件:什么时候触发
事件覆盖了会话的完整生命周期,最常用的八个:
| 事件 | 触发时机 | 能不能拦 |
|---|---|---|
| SessionStart | 会话开始、恢复或压缩后 | 不能,输出变成上下文 |
| UserPromptSubmit | 你按下回车、模型看到提示词之前 | 能,拒绝这条提示 |
| PreToolUse | 工具执行之前 | 能,拒绝这次调用 |
| PostToolUse | 工具成功执行之后 | 不能,但可以把反馈告诉模型 |
| PostToolUseFailure | 工具执行失败之后 | 不能 |
| SubagentStop | 子代理结束时 | 能,强制继续 |
| Stop | 主代理回答结束时 | 能,强制继续 |
| PreCompact | 上下文压缩之前 | 不能 |
"能不能拦"是最关键的一列:PreToolUse 是唯一的执行前关卡,想拦截危险操作只能用它;PostToolUse 再快也已经晚了——文件已经改了、命令已经跑了,它只适合做格式化、跑 lint 这种事后动作。
Hook 怎么和 Claude Code 通话
每个 Hook 收到两样东西、回三样东西:
- 收到:事件相关的 JSON 数据,从 stdin 传进来。比如 PreToolUse 会告诉你工具名和参数,Bash 工具的话能看到完整命令。
- 回去:stdout 的内容会被当作上下文交给模型;stderr 在出错时展示;退出码决定动作——0 表示通过,2 表示拦截(只对能拦的事件有效,stderr 里的文字会作为拦截原因显示给模型)。
SessionStart 和 UserPromptSubmit 比较特殊:它们的 stdout 输出会自动变成上下文。所以这两个事件的 Hook 常用来"注入信息":会话一开就把 git 状态、当前分支贴进来;提交提示词之前先把项目规范追加进去。
三个可以直接抄的 Hook
- 拦截危险命令:改 .env 和 rm -rf 想都别想
这是 PreToolUse 最典型的用法,配在项目级 .claude/settings.json 里,全团队共享:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 .claude/hooks/guard.py"
}
]
}
]
}
}
guard.py 从 stdin 读 JSON,检查命令里有没有 rm -rf、有没有写 .env:
import json, sys
data = json.load(sys.stdin)
cmd = data.get("tool_input", {}).get("command", "")
dangerous = ["rm -rf", ".env"]
for word in dangerous:
if word in cmd:
print(f"已拦截:命令包含 {word},请手动确认后再执行", file=sys.stderr)
sys.exit(2)
命中就退出码 2,工具调用直接被拦下,模型会收到 stderr 里的原因。没命中就正常退出,调用继续。matcher 是 Bash,表示只对 Bash 工具生效,不用给每个工具都配一遍;想全量拦截就把 matcher 写成 *。
注意这个例子故意写得简单:真实项目里黑名单要按自己的危险操作清单来,别照抄两个关键词就以为万事大吉。黑名单的意义是兜底,不是替代 code review。
- 改完代码自动格式化:PostToolUse
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
}
]
}
]
}
}
每次模型改完文件,prettier 自动跑一遍。|| true 是故意的:格式化失败也不能让 Hook 报错去打断会话——事后动作的 Hook 必须保证自己永远成功,否则它自己就成了故障源。
- 防止密钥被粘进提示词:UserPromptSubmit
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "python3 .claude/hooks/secrets.py"
}
]
}
]
}
}
secrets.py 读提示词文本,用正则扫 sk-、AKIA、ghp_ 这类密钥前缀,扫到了就退出码 2 拒绝提交。复制粘贴一段报错日志时顺手带上密钥,是最常见的泄密方式,靠人每次检查不现实,靠 Hook 一次写好就一直生效。
三、命令和 Hooks 怎么分工
| 场景 | 用哪个 | 为什么 |
|---|---|---|
| 每天重复三遍以上的提示词 | 自定义命令 | 存一次,以后一句话调用 |
| 团队统一的工作流(审 PR、发版检查) | 项目级命令 | 提交进 git,全员同一套标准 |
| 危险操作拦截(删库、改密钥文件) | PreToolUse Hook | 不经过模型,机制上拦得住 |
| 改完代码自动格式化、跑 lint | PostToolUse Hook | 事后动作,不用模型记得补一句 |
| 提示词里混进密钥 | UserPromptSubmit Hook | 提交前最后一道关 |
| 会话一开就想看到 git 状态 | SessionStart Hook | 输出自动进上下文 |
一句话:凡是"你希望每次都发生"的事,交给 Hook;凡是"你有时候想这么干"的事,写成命令。
四、从哪开始:先三个命令,再两个 Hook
不用一次配全。按这个顺序,半天就能搭完:
- 先写三个最常用的命令:/commit、/review-pr、/changelog,放 ~/.claude/commands/,当天就能省下重复打字的时间。
- 再加两个 Hook:PreToolUse 拦截你最怕的那一两个危险操作,PostToolUse 接自动格式化。先个人级验证好用,再挪到项目级 .claude/settings.json 提交给团队。
- 调试时用 /hooks 看配置是否被正确加载,Hook 不触发先检查三点:JSON 格式对不对、脚本路径是不是绝对路径、脚本有没有可执行权限。大部分"Hook 没生效"都是这三个原因。
Claude Code 的能力上限,一半在模型,一半在你给它搭的工作台。提示词写得再好,也只是每一轮的临场发挥;命令和 Hooks 是把"每次都该这么做"写进配置里,让它变成默认行为。先从三个命令开始,你会发现省下的不只是打字时间,还有每次都要盯着它别犯低级错误的精力。
2万+



被折叠的 条评论
为什么被折叠?



