025、自定义 Slash Command别名到带参数复杂命令的开发从一次凌晨告警说起凌晨两点手机震了。生产环境的日志告警显示某个微服务的错误率突然飙升到15%。我下意识想敲kubectl get pods -n production | grep error但手边只有手机终端连上跳板机后还得先查集群上下文。那一刻我意识到如果有个/prod-error命令能直接帮我查最近5分钟的错误日志我至少能少敲20个字符、少等两次命令回显。这就是 Slash Command 的价值——不是炫技是救命。别把 Slash Command 当别名用很多人第一次接触 Claude Code 的自定义命令时会写成这样# 别这样写这只是一个别名commands:/deploy:description:部署服务command:kubectl apply -f deploy.yaml这本质上就是个 shell alias毫无灵魂。真正的 Slash Command 应该能接受参数、处理上下文、甚至调用外部 API。我们来看一个生产级别的例子。带参数命令的骨架先搭一个能处理参数的/rollback命令用于回滚部署commands:/rollback:description:回滚指定服务到历史版本arguments:-name:servicedescription:服务名称如 user-servicerequired:true-name:revisiondescription:目标版本号不传则回滚到上一个版本required:falsedefault:previouscommand:|# 这里踩过坑必须显式处理参数为空的情况 SERVICE{{service}} REVISION{{revision}}if[$REVISION previous]; then echo 正在回滚 $SERVICE 到上一个版本... kubectl rollout undo deployment/$SERVICE-n production else echo 正在回滚 $SERVICE 到版本 $REVISION... kubectl rollout undo deployment/$SERVICE--to-revision$REVISION-n production fi# 等待30秒看状态别直接退出sleep 30 kubectl rollout status deployment/$SERVICE-n production注意{{service}}和{{revision}}这种模板语法——Claude Code 会在执行前把用户输入填充进去。如果用户只输入/rollback user-servicerevision就会自动取默认值previous。复杂命令多步骤 条件判断单行命令好写但真实场景往往是多步骤的。比如/hotfix命令需要先拉代码、改版本号、构建镜像、推送到仓库、再部署commands:/hotfix:description:紧急修复修改代码、构建镜像并部署arguments:-name:servicedescription:服务名required:true-name:branchdescription:修复分支名required:true-name:versiondescription:新版本号如 v1.2.3required:truecommand:|SERVICE{{service}} BRANCH{{branch}} VERSION{{version}}# 第一步拉取代码并切分支echo 拉取 $SERVICE 代码分支:$BRANCH cd /workspace/$SERVICE git fetch origin git checkout-b $BRANCH origin/main||{echo 分支创建失败可能已存在; exit 1;}# 第二步修改版本号文件# 这里踩过坑不同项目版本号文件位置不一样得先检测if[-f VERSION]; then echo $VERSIONVERSION elif[-f package.json]; thensed -i s/\version\:\.*\/\version\:\$VERSION\/ package.json else echo 无法识别版本文件请手动修改 exit 1 fi# 第三步构建并推送docker build-t registry.internal/$SERVICE:$VERSION . docker push registry.internal/$SERVICE:$VERSION# 第四步部署kubectl set image deployment/$SERVICE $SERVICEregistry.internal/$SERVICE:$VERSION-n production echo 热修复完成版本 $VERSION 已部署这个命令里用了|| { ...; exit 1; }这种 bash 错误处理——别指望 Claude Code 帮你做错误恢复它只会按顺序执行你的脚本失败了就报错。所以每一步都要自己兜底。参数校验别让用户乱填用户输入是不可信的。我见过有人把/deploy命令的namespace参数填成; rm -rf /——虽然 Claude Code 有沙箱但养成校验习惯没坏处commands:/deploy:arguments:-name:namespacedescription:命名空间required:true# 这里用正则限制只允许小写字母和连字符pattern:^[a-z0-9-]$-name:image_tagdescription:镜像标签required:truepattern:^v[0-9]\\.[0-9]\\.[0-9]$command:|NAMESPACE{{namespace}} TAG{{image_tag}}# 双重校验正则过滤后还要检查长度if[${#NAMESPACE} -gt 63 ]; thenecho 命名空间长度不能超过63个字符 exit 1 fi kubectl set image deployment/app appmyapp:$TAG-n $NAMESPACEpattern字段是 Claude Code 内置的校验机制但别完全依赖它——有些版本的正则引擎实现有差异我遇到过 pattern 没生效的情况所以脚本里又加了一层长度检查。动态参数从环境变量和文件读取有时候参数不是用户输入的而是从当前环境推断的。比如/status命令自动检测当前 k8s 上下文commands:/status:description:查看当前集群状态command:|# 自动获取当前上下文别让用户手动传 CONTEXT$(kubectl config current-context 2/dev/null || echo unknown) NAMESPACE$(kubectl config view --minify -o jsonpath{..namespace} 2/dev/null || echo default)echo 当前集群:$CONTEXTecho 当前命名空间:$NAMESPACE echo ---# 这里踩过坑有些集群没有 metrics-server直接 top 会报错if kubectl top nodes/dev/null;then echo 节点资源使用: kubectl top nodes else echo metrics-server 不可用跳过资源监控 fi echo --- echo 异常 Pod: kubectl get pods--all-namespaces|grep-E CrashLoopBackOff|Error|ImagePullBackOff这个命令没有参数但通过环境检测实现了“智能”行为。用户只需要敲/status就能拿到当前上下文的关键信息。组合命令调用其他命令Slash Command 可以互相调用但别写成递归死循环commands:/full-check:description:完整检查日志 状态 资源command:|echo 开始完整检查 # 调用其他命令注意这里用的是 Claude Code 内部机制不是 shell 管道/status echo --- echo 最近错误日志: /logs--service all--level error--since 5m echo --- echo 磁盘使用: df-h /|tail-1这种组合方式有个坑被调用的命令如果定义了参数你必须显式传值。比如/logs命令如果要求--service参数是 required这里不传就会报错。所以设计命令时尽量给参数设默认值。调试技巧打印执行计划写复杂命令时我习惯先打印一遍“执行计划”让用户确认后再执行commands:/migrate-db:description:数据库迁移危险操作arguments:-name:directiondescription:迁移方向: up/downrequired:trueenum:[up,down]-name:stepsdescription:迁移步数required:falsedefault:1command:|DIR{{direction}} STEPS{{steps}}echo ⚠️ 即将执行数据库迁移:echo 方向:$DIRecho 步数:$STEPSecho 数据库:$DATABASE_URL (从环境变量读取) echo echo 输入 YES 确认执行其他任意键取消: read CONFIRM if[$CONFIRM!YES]; then echo 已取消 exit 0 fi# 这里踩过坑migrate 命令的 -steps 参数在不同版本行为不同if[$DIR up]; then migrate-path /migrations-database $DATABASE_URL up $STEPS else migrate-path /migrations-database $DATABASE_URL down $STEPS fienum字段限制了direction只能取up或down用户输别的会直接报错。加上确认步骤防止手滑。个人经验别过度设计写 Slash Command 最容易犯的错是“想太多”。我见过有人给/deploy命令加了十几个参数包括--rollback-on-failure、--canary-percentage、--timeout……结果团队里没人记得住最后还是手动敲 kubectl。我的原则是一个命令只解决一个痛点。/rollback就只做回滚/hotfix就只做热修复。如果某个命令的参数超过3个说明它应该拆成两个命令。另外命令的command字段里尽量用 bash 而不是 Claude Code 的 DSL。bash 是通用语言换到任何 CI/CD 环境都能跑DSL 绑定在 Claude Code 上哪天换工具就废了。最后所有命令都要加set -e或者显式错误处理。Claude Code 不会帮你回滚失败的操作——它只会告诉你“命令执行失败”然后让你自己擦屁股。
025、自定义 Slash Command：别名到带参数复杂命令的开发
025、自定义 Slash Command别名到带参数复杂命令的开发从一次凌晨告警说起凌晨两点手机震了。生产环境的日志告警显示某个微服务的错误率突然飙升到15%。我下意识想敲kubectl get pods -n production | grep error但手边只有手机终端连上跳板机后还得先查集群上下文。那一刻我意识到如果有个/prod-error命令能直接帮我查最近5分钟的错误日志我至少能少敲20个字符、少等两次命令回显。这就是 Slash Command 的价值——不是炫技是救命。别把 Slash Command 当别名用很多人第一次接触 Claude Code 的自定义命令时会写成这样# 别这样写这只是一个别名commands:/deploy:description:部署服务command:kubectl apply -f deploy.yaml这本质上就是个 shell alias毫无灵魂。真正的 Slash Command 应该能接受参数、处理上下文、甚至调用外部 API。我们来看一个生产级别的例子。带参数命令的骨架先搭一个能处理参数的/rollback命令用于回滚部署commands:/rollback:description:回滚指定服务到历史版本arguments:-name:servicedescription:服务名称如 user-servicerequired:true-name:revisiondescription:目标版本号不传则回滚到上一个版本required:falsedefault:previouscommand:|# 这里踩过坑必须显式处理参数为空的情况 SERVICE{{service}} REVISION{{revision}}if[$REVISION previous]; then echo 正在回滚 $SERVICE 到上一个版本... kubectl rollout undo deployment/$SERVICE-n production else echo 正在回滚 $SERVICE 到版本 $REVISION... kubectl rollout undo deployment/$SERVICE--to-revision$REVISION-n production fi# 等待30秒看状态别直接退出sleep 30 kubectl rollout status deployment/$SERVICE-n production注意{{service}}和{{revision}}这种模板语法——Claude Code 会在执行前把用户输入填充进去。如果用户只输入/rollback user-servicerevision就会自动取默认值previous。复杂命令多步骤 条件判断单行命令好写但真实场景往往是多步骤的。比如/hotfix命令需要先拉代码、改版本号、构建镜像、推送到仓库、再部署commands:/hotfix:description:紧急修复修改代码、构建镜像并部署arguments:-name:servicedescription:服务名required:true-name:branchdescription:修复分支名required:true-name:versiondescription:新版本号如 v1.2.3required:truecommand:|SERVICE{{service}} BRANCH{{branch}} VERSION{{version}}# 第一步拉取代码并切分支echo 拉取 $SERVICE 代码分支:$BRANCH cd /workspace/$SERVICE git fetch origin git checkout-b $BRANCH origin/main||{echo 分支创建失败可能已存在; exit 1;}# 第二步修改版本号文件# 这里踩过坑不同项目版本号文件位置不一样得先检测if[-f VERSION]; then echo $VERSIONVERSION elif[-f package.json]; thensed -i s/\version\:\.*\/\version\:\$VERSION\/ package.json else echo 无法识别版本文件请手动修改 exit 1 fi# 第三步构建并推送docker build-t registry.internal/$SERVICE:$VERSION . docker push registry.internal/$SERVICE:$VERSION# 第四步部署kubectl set image deployment/$SERVICE $SERVICEregistry.internal/$SERVICE:$VERSION-n production echo 热修复完成版本 $VERSION 已部署这个命令里用了|| { ...; exit 1; }这种 bash 错误处理——别指望 Claude Code 帮你做错误恢复它只会按顺序执行你的脚本失败了就报错。所以每一步都要自己兜底。参数校验别让用户乱填用户输入是不可信的。我见过有人把/deploy命令的namespace参数填成; rm -rf /——虽然 Claude Code 有沙箱但养成校验习惯没坏处commands:/deploy:arguments:-name:namespacedescription:命名空间required:true# 这里用正则限制只允许小写字母和连字符pattern:^[a-z0-9-]$-name:image_tagdescription:镜像标签required:truepattern:^v[0-9]\\.[0-9]\\.[0-9]$command:|NAMESPACE{{namespace}} TAG{{image_tag}}# 双重校验正则过滤后还要检查长度if[${#NAMESPACE} -gt 63 ]; thenecho 命名空间长度不能超过63个字符 exit 1 fi kubectl set image deployment/app appmyapp:$TAG-n $NAMESPACEpattern字段是 Claude Code 内置的校验机制但别完全依赖它——有些版本的正则引擎实现有差异我遇到过 pattern 没生效的情况所以脚本里又加了一层长度检查。动态参数从环境变量和文件读取有时候参数不是用户输入的而是从当前环境推断的。比如/status命令自动检测当前 k8s 上下文commands:/status:description:查看当前集群状态command:|# 自动获取当前上下文别让用户手动传 CONTEXT$(kubectl config current-context 2/dev/null || echo unknown) NAMESPACE$(kubectl config view --minify -o jsonpath{..namespace} 2/dev/null || echo default)echo 当前集群:$CONTEXTecho 当前命名空间:$NAMESPACE echo ---# 这里踩过坑有些集群没有 metrics-server直接 top 会报错if kubectl top nodes/dev/null;then echo 节点资源使用: kubectl top nodes else echo metrics-server 不可用跳过资源监控 fi echo --- echo 异常 Pod: kubectl get pods--all-namespaces|grep-E CrashLoopBackOff|Error|ImagePullBackOff这个命令没有参数但通过环境检测实现了“智能”行为。用户只需要敲/status就能拿到当前上下文的关键信息。组合命令调用其他命令Slash Command 可以互相调用但别写成递归死循环commands:/full-check:description:完整检查日志 状态 资源command:|echo 开始完整检查 # 调用其他命令注意这里用的是 Claude Code 内部机制不是 shell 管道/status echo --- echo 最近错误日志: /logs--service all--level error--since 5m echo --- echo 磁盘使用: df-h /|tail-1这种组合方式有个坑被调用的命令如果定义了参数你必须显式传值。比如/logs命令如果要求--service参数是 required这里不传就会报错。所以设计命令时尽量给参数设默认值。调试技巧打印执行计划写复杂命令时我习惯先打印一遍“执行计划”让用户确认后再执行commands:/migrate-db:description:数据库迁移危险操作arguments:-name:directiondescription:迁移方向: up/downrequired:trueenum:[up,down]-name:stepsdescription:迁移步数required:falsedefault:1command:|DIR{{direction}} STEPS{{steps}}echo ⚠️ 即将执行数据库迁移:echo 方向:$DIRecho 步数:$STEPSecho 数据库:$DATABASE_URL (从环境变量读取) echo echo 输入 YES 确认执行其他任意键取消: read CONFIRM if[$CONFIRM!YES]; then echo 已取消 exit 0 fi# 这里踩过坑migrate 命令的 -steps 参数在不同版本行为不同if[$DIR up]; then migrate-path /migrations-database $DATABASE_URL up $STEPS else migrate-path /migrations-database $DATABASE_URL down $STEPS fienum字段限制了direction只能取up或down用户输别的会直接报错。加上确认步骤防止手滑。个人经验别过度设计写 Slash Command 最容易犯的错是“想太多”。我见过有人给/deploy命令加了十几个参数包括--rollback-on-failure、--canary-percentage、--timeout……结果团队里没人记得住最后还是手动敲 kubectl。我的原则是一个命令只解决一个痛点。/rollback就只做回滚/hotfix就只做热修复。如果某个命令的参数超过3个说明它应该拆成两个命令。另外命令的command字段里尽量用 bash 而不是 Claude Code 的 DSL。bash 是通用语言换到任何 CI/CD 环境都能跑DSL 绑定在 Claude Code 上哪天换工具就废了。最后所有命令都要加set -e或者显式错误处理。Claude Code 不会帮你回滚失败的操作——它只会告诉你“命令执行失败”然后让你自己擦屁股。
