1. 为什么我要给 Claude Code 塞进 10 个中文命令用 Claude Code 写代码这件事最开始的新鲜感过去之后真正让人头疼的其实不是模型能力而是交互摩擦。你每次打开终端面对的是一个空白的对话窗口想让它帮你做点事得先用英文把上下文、约束、输出格式描述一遍。写一次两次还行天天写就变成了体力活。我自己的日常场景大概是这样几类接手一个陌生仓库要快速摸清目录结构和入口文件写完一段逻辑要让它帮我做一轮代码审查提交前要生成符合团队规范的 commit message偶尔还要把一段中文需求直接翻译成可执行的实现方案。这些事每次都要重新组织提示词效率极低。后来我意识到Claude Code 本身是支持**自定义命令custom slash commands**的也就是你可以把常用的提示词模板固化成一个个/xxx命令直接在会话里调用。这个机制本质上就是把提示词工程从每次手写变成了一次性资产沉淀。于是我做了一件事把 10 个高频的中文命令装进 Claude Code形成一个轻量的 AI 编程工作流包。这篇内容适合两类人看一类是已经在用 Claude Code 或者 Codex CLI 这类终端 AI 编程工具但还停留在每次手打提示词阶段的开发者另一类是刚接触 AI 编程工作流想搞清楚命令化到底能带来什么实际收益的人。我会把这 10 个命令的设计思路、目录结构、每个命令的具体写法、踩过的坑以及怎么和 VS Code、本地模型配合全部拆开讲清楚。读完你基本可以照着抄一套属于自己的工作流。需要先说明一点下面所有命令的具体实现都是基于 Claude Code 官方文档里 custom commands 的通用机制加上我自己实际使用中总结的写法。不同版本可能在细节上有差异但核心逻辑是稳定的。2. 自定义命令到底是怎么被 Claude Code 加载的在动手写命令之前必须先把加载机制搞清楚否则你会遇到我明明建了文件为什么/里找不到这种问题。2.1 命令文件的存放位置与作用域Claude Code 的自定义命令本质上是 Markdown 文件放在特定目录下文件名就是命令名。它有两个作用域项目级放在项目根目录的.claude/commands/下。这个命令只在这个项目里可用适合放团队共享的、和项目强相关的命令比如按本项目的分层规范生成 Service 层代码。用户级放在用户主目录的~/.claude/commands/下。这个命令在你所有项目里都能用适合放通用的、和个人习惯绑定的命令比如用中文帮我审查这段代码。我自己的做法是通用能力放用户级项目约定放项目级。这样换项目的时候通用命令跟着我走项目特有的命令跟着仓库走职责清晰。一个典型的目录长这样~/.claude/commands/ ├── review.md ├── explain.md ├── commit.md ├── refactor.md └── ... your-project/.claude/commands/ ├── api-spec.md └── db-migration.md2.2 命令名、参数与 frontmatter文件名去掉.md就是命令名。比如review.md对应/review。这里有个容易踩的坑文件名不要用中文。虽然理论上某些环境能识别但终端输入、补全、跨平台一致性都会出问题。正确做法是文件名用英文命令内容用中文。命令文件支持 YAML frontmatter可以声明描述、允许的参数等。一个基础结构--- description: 对当前改动做一轮中文代码审查 --- 请你扮演一位资深的后端工程师对下面的代码做一轮审查……description会出现在你输入/时的命令列表里写清楚能大幅降低我当初为啥建这个命令的遗忘成本。2.3 参数注入与上下文引用这是让命令真正活起来的关键。Claude Code 的命令支持几种动态内容注入$ARGUMENTS把你在命令后面跟的所有内容原样传进来。比如/review 重点关注并发安全那么$ARGUMENTS就是重点关注并发安全。$1、$2按位置取参数。文件路径在命令正文里引用文件内容Claude Code 会把文件读进来作为上下文。我实测下来$ARGUMENTS是最实用的。它让你在保持命令模板固定的同时还能针对当次任务做微调。比如审查命令里写额外关注点$ARGUMENTS你调用时补一句重点看空指针它就只往那个方向使劲。注意$ARGUMENTS为空时有些版本会原样保留这个占位符导致提示词里出现奇怪的字符串。稳妥做法是在命令正文里加一句若未提供额外关注点则忽略此项让模型自己兜底。2.4 为什么用 Markdown 而不是脚本有人会问为什么不直接写 shell 脚本调用 API因为 Claude Code 的命令机制是在会话上下文里执行的它能直接看到你当前的对话历史、打开的文件、git 状态。脚本是隔离的拿不到这些。用 Markdown 命令等于把提示词挂载到了当前会话的记忆上这是它最大的价值。3. 这 10 个中文命令分别解决什么问题下面是我实际装进去的 10 个命令。我按输入侧和输出侧分了两组输入侧负责帮我理解代码输出侧负责帮我产出代码和提交物。3.1 输入侧读懂代码的 5 个命令/explain——用中文讲清一段代码在干什么。这是使用频率最高的一个。我经常接手别人的模块直接选中一段代码敲/explain它会用中文把这段逻辑、依赖、副作用讲一遍。命令正文里我会强调先讲业务意图再讲技术实现最后指出潜在风险避免它一上来就逐行翻译。/trace——追踪一个函数的调用链。给定一个函数名让它顺着代码库找出谁调用了它、它又调用了谁。这个命令的价值在于它逼着模型去做跨文件检索而不是只看当前文件。我会在命令里要求它输出调用链时标注文件路径和行号方便我跳转核对。/structure——快速摸清一个目录的组织方式。新仓库第一件事就是敲这个。它会输出目录树、每个目录的职责、入口文件在哪。比我自己ls一遍再猜要快得多。/deps——分析一个模块的依赖关系。尤其是排查循环依赖、找出某个包被谁引入的时候特别好用。命令里我会让它区分直接依赖和传递依赖。/why——解释某段代码为什么这么写。这个偏考古。看到一段奇怪的兼容代码敲/why让它结合 git 历史和注释推测动机。它不一定对但经常能给出有价值的猜测方向。3.2 输出侧产出代码与提交物的 5 个命令/review——中文代码审查。前面提过支持$ARGUMENTS追加关注点。我会要求它按正确性、边界条件、性能、可读性、安全五个维度输出每个维度下只列真正有问题的点没问题的维度直接说无。/refactor——按指定目标重构。比如/refactor 把这段逻辑抽成独立函数并加单元测试。命令正文里我会强调重构后必须保证行为不变并说明你做了哪些等价变换。/commit——生成符合规范的提交信息。它会读取当前 git diff按 Conventional Commits 格式生成中文提交信息。这个命令帮我省了大量组织语言的时间。/test——为指定代码生成测试用例。我会要求它覆盖正常路径、边界值、异常路径三类并标注每个用例的意图。/doc——生成中文文档注释。针对导出的函数、类、接口生成符合团队注释规范的中文文档。把这 10 个命令列成一张表方便你对照自己的需求取舍命令类型核心作用是否常用/explain输入中文讲解代码逻辑极高/trace输入追踪调用链高/structure输入摸清目录结构高/deps输入分析依赖关系中/why输入推测代码动机中/review输出中文代码审查极高/refactor输出定向重构高/commit输出生成提交信息极高/test输出生成测试用例高/doc输出生成中文注释中4. 逐个拆解命令正文怎么写才有效光有名字没用命令正文的写法直接决定输出质量。我挑几个最有代表性的把完整写法和设计理由讲透。4.1/review的完整写法与维度设计--- description: 对选中代码或当前改动做中文代码审查 --- 你是一位有十年经验的后端工程师请对下面的代码做一轮严格但务实的审查。 审查维度按顺序输出每个维度下只列真正存在的问题无问题则写无 1. 正确性逻辑是否有误是否满足预期行为 2. 边界条件空值、越界、并发、超时等场景是否处理 3. 性能是否存在明显的低效操作如循环内查询、重复计算 4. 可读性命名、结构、注释是否清晰 5. 安全是否存在注入、越权、敏感信息泄露风险 额外关注点$ARGUMENTS 输出要求 - 每个问题必须给出具体位置函数名或行号范围 - 每个问题必须给出修改建议不要只说有问题 - 不要为了凑数而提出无关痛痒的建议这个命令的设计核心是结构化输出。如果不限定维度模型会随机发挥有时只讲性能有时只讲命名你没法形成稳定的预期。限定五个维度后每次审查的覆盖面是一致的我扫一眼就知道哪块需要细看。$ARGUMENTS放在最后作为额外关注点是因为它属于增量信息不应该打乱主维度的结构。4.2/commit如何读取 git 状态--- description: 根据当前 git 改动生成中文提交信息 --- 请根据当前的 git 改动生成一条符合 Conventional Commits 规范的中文提交信息。 要求 - 格式type(scope): subject - type 从 feat/fix/refactor/docs/test/chore 中选择 - subject 用中文不超过 50 字动词开头 - 如果改动涉及多个不相关的内容建议拆分成多条提交 - 在提交信息下方用列表列出本次改动的主要文件及原因 额外说明$ARGUMENTS这里的关键是让模型自己去看 git diff。Claude Code 在会话里能执行终端命令所以它会主动跑git diff和git status。我实测下来只要命令里明确说根据当前 git 改动它就会去读不需要我手动贴 diff。提示如果你的改动还没git add有些版本可能只看到已暂存的部分。稳妥做法是提交前先git add -A或者直接在命令里加一句包括未暂存的改动。4.3/explain的三段式输出--- description: 用中文讲解选中代码 --- 请用中文讲解下面的代码按三段式输出 第一段业务意图。这段代码在整个系统里承担什么职责解决什么问题。 第二段技术实现。用了哪些关键 API、数据结构、算法核心流程是什么。 第三段潜在风险。有没有边界问题、性能隐患、可维护性隐患。 要求 - 不要逐行翻译代码 - 遇到不熟悉的第三方库先说明它的作用再讲用法 - 如果代码里有明显的坏味道直接指出来 补充说明$ARGUMENTS不要逐行翻译这句是必须加的。不加的话模型很容易退化成这一行定义了一个变量那一行做了一个判断这种废话。三段式结构逼着它先抽象再具体信息密度高很多。4.4/refactor的等价性约束重构类命令最大的风险是模型顺手改了行为。所以我在命令里加了硬约束--- description: 按指定目标重构选中代码 --- 请按下面的目标重构代码$ARGUMENTS 硬性约束 - 重构后必须保证外部行为完全不变 - 不允许修改公开接口的签名除非我明确要求 - 每做一处改动说明它属于哪种等价变换提取函数、内联、重命名、消除重复等 - 如果发现无法在保持行为不变的前提下完成目标停下来告诉我原因不要强行改 输出格式 1. 重构后的完整代码 2. 改动清单每项说明变换类型和理由 3. 需要我确认的风险点停下来告诉我原因这一条非常重要。没有它模型会为了完成任务而做出妥协性的改动反而引入 bug。4.5/test的三类覆盖要求--- description: 为选中代码生成测试用例 --- 请为下面的代码生成测试用例覆盖三类场景 1. 正常路径典型输入下的预期输出 2. 边界值空值、零、最大值、最小值、临界长度 3. 异常路径非法输入、依赖失败、超时 要求 - 每个用例前用注释说明它的意图 - 使用项目现有的测试框架和断言风格 - 如果某个场景无法测试说明原因 - 不要生成重复覆盖的用例 补充$ARGUMENTS使用项目现有的测试框架这句让模型先去读项目里的测试文件模仿现有风格而不是默认用某个它熟悉的框架。这一点在接手老项目时特别有用。5. 把命令和工作流串起来一次真实的开发闭环单个命令好用但真正的效率提升来自把它们串成一条流水线。我拿一个真实场景走一遍接手一个陌生的订单模块要加一个超时自动取消的功能。5.1 第一步用/structure和/trace建立地图进仓库先敲/structure src/order它会输出订单模块的目录结构、每个文件的职责。然后我找到订单状态变更的入口函数敲/trace changeOrderStatus它会列出这个函数被哪些地方调用、内部又调用了什么。这两步做完我脑子里就有了一张调用图。整个过程大概两分钟比我自己翻文件快得多。关键是/trace会标注文件路径和行号我可以直接跳过去核对不会盲信模型。5.2 第二步用/explain和/why吃透关键逻辑找到状态机相关的代码后敲/explain让它讲清楚状态流转规则。如果看到一段奇怪的兼容代码比如当状态为 X 且渠道为 Y 时跳过校验就敲/why让它结合 git 历史推测原因。这里有个经验/why的输出要当作假设而不是结论。它经常能猜对方向但细节可能不准。我会拿它的猜测去 git log 里验证。5.3 第三步用/refactor和/test落地改动理解清楚后开始改。我会先让/refactor把要改的逻辑抽成独立函数再让/test为这个新函数生成测试。注意顺序先重构再测试因为重构后函数边界清晰测试更好写。改完之后敲/review追加参数重点关注定时任务的并发安全。它会按五个维度审一遍通常能揪出我漏掉的边界情况。5.4 第四步用/commit收尾最后git add -A敲/commit它会生成一条规范的中文提交信息。如果改动涉及多个不相关的内容它会建议我拆分提交这个提醒很有价值。整条流水线走下来我基本不需要手写提示词所有交互都是/xxx加少量参数。这就是命令化的核心收益把提示词从一次性消耗品变成可复用资产。6. 踩过的坑命令不生效、参数丢失、上下文超长这部分是我实际踩过的坑按排查链路写你可以对照复现。6.1 命令建好了但/列表里找不到第一次建命令时我在项目根目录建了commands/review.md结果敲/死活找不到。排查过程先确认目录名。Claude Code 认的是.claude/commands/不是commands/。我漏了点前缀。再确认文件名。我一开始用了代码审查.md改成review.md后立刻出现。最后确认重启。有些版本需要重启会话才会重新扫描命令目录。结论目录必须是.claude/commands/文件名必须英文改完重启会话。这三条记住了基本不会再踩。6.2$ARGUMENTS传进去变成空字符串有次我调用/review没带参数结果提示词里出现了额外关注点后面空着模型开始自己编关注点。后来我在命令正文里加了一句兜底额外关注点$ARGUMENTS 若上面为空则忽略此项按默认维度审查即可这样即使参数为空模型也知道该怎么做。这个坑的本质是占位符替换是纯文本操作不会自动处理空值得靠提示词兜底。6.3 上下文超长导致命令执行到一半被截断这个坑最隐蔽。我有个/structure命令让它扫描整个仓库结果在大项目里上下文直接爆了输出被截断只分析了前几个目录。解决办法有两个缩小范围命令里明确要求只分析我指定的目录不要递归整个仓库。调用时传目录参数。分而治之先让它输出顶层目录我再针对某个子目录单独跑一次。我现在的/structure命令正文里第一句就是只分析 $ARGUMENTS 指定的目录不要扫描其他目录。这样上下文可控输出也聚焦。注意上下文超长是终端 AI 编程工具的通用问题不只是 Claude Code。养成给命令限定范围的习惯比事后补救有效得多。6.4 命令之间互相污染上下文有一次我连续敲了/explain、/review、/refactor结果/refactor的输出里混进了前面审查阶段的建议改得莫名其妙。原因是这些命令都在同一个会话里执行共享上下文。解决办法重活之间用/clear或开新会话。我现在养成习惯一个命令的输出用完、结论记下来之后就清一次上下文。尤其是/refactor这种会改代码的命令一定要在干净的上下文里跑。7. 和 VS Code、本地模型、Codex CLI 的配合方式命令包不是孤立的它得嵌进你现有的工具链里。7.1 在 VS Code 里用命令包如果你用 VS Code 的 Claude Code 扩展命令目录的机制是一样的。项目级命令放在工作区根目录的.claude/commands/用户级放在主目录。区别在于VS Code 里你可以直接选中编辑器里的代码再敲命令比终端里手动贴代码方便很多。我自己的分工是终端里跑/structure、/trace这类需要跨文件检索的命令VS Code 里跑/explain、/review这类针对选中代码的命令。各取所长。7.2 接本地模型时的注意事项有些场景下你会想让 Claude Code 调用本地模型比如内网环境、数据不能外传。这时候命令包依然可用因为命令只是提示词模板和底层模型无关。但要注意两点本地模型的指令遵循能力通常弱一些命令正文要写得更明确减少歧义。本地模型的上下文窗口可能更小/structure这类命令的范围限制要更严格。我实测下来命令模板越结构化本地模型的输出越稳定。所以前面强调的分维度、给格式的写法在本地模型场景下收益更大。7.3 和 Codex CLI 的命令体系对照Codex CLI 也有类似的提示词模板机制思路是一致的把常用提示词固化成可调用单元。区别主要在目录约定和参数语法上。如果你同时用两个工具建议保持命令名一致比如两边都叫/review这样肌肉记忆可以复用不用记两套。我自己的做法是把命令正文抽成一份共享的 Markdown然后分别放到两个工具的目录下。改一处同步另一处。虽然有点手工但比维护两套完全不同的提示词省心。8. 让命令包长期可用的几个维护习惯命令包建起来容易维护下去难。分享几个我坚持的习惯。8.1 每个命令都要有 description前面提过description会出现在命令列表里。我见过太多人建了一堆命令过两个月自己都忘了/xyz是干嘛的。写清楚 description等于给未来的自己留了张便签。8.2 定期清理低频命令命令不是越多越好。我一开始建了二十多个结果常用的就那十个剩下的反而干扰补全。后来我定了个规则连续一个月没用过的命令删掉或归档。保持命令列表精简补全才快。8.3 用版本控制管理项目级命令项目级的.claude/commands/我会提交到 git 仓库。这样团队里每个人拉下来就有一套统一的命令新人入职不用自己摸索提示词。这其实是把团队提示词规范代码化了比写在文档里靠谱得多。8.4 命令正文里的经验要持续回填每次/review揪出一个我没想到的问题类型我就会把这类问题补进命令的审查维度里。时间长了命令包会越来越贴合我的实际需求。这是命令化相对手写提示词最大的优势它可以积累。9. 我实际用下来最值钱的三个细节最后分享三个我踩过坑之后才明白的细节都是文档里不会写的。第一个是命令正文要写不要做什么。模型天生倾向于多做事你不限制它它就会在/explain里顺手给你重构代码在/review里顺手帮你改文件。明确写只输出分析不要修改任何文件能省掉很多回滚的麻烦。第二个是参数尽量用自然语言而不是结构化格式。我试过用 JSON 传参结果模型经常解析错。后来改成直接写重点关注并发安全反而稳定。终端场景下自然语言就是最好的接口。第三个是命令的输出要能直接复制走。我会要求模型把最终代码放在独立的代码块里把结论放在列表里。这样我可以直接复制粘贴不用在对话里挑挑拣拣。这个细节看似小但每天用几十次累积起来省的时间很可观。这套命令包我从最初的三个命令慢慢迭代到现在的十个中间删过、改过、合并过。它不是什么一劳永逸的方案而是一个跟着我使用习惯一起生长的工具。如果你也想搭一套建议从/explain和/review这两个最高频的开始用顺了再往外扩。