Claude Code 中文命令工作流：10 个自定义命令提升开发效率

1. 为什么我要折腾这套中文命令工作流用 Claude Code 做开发的人大概都经历过这样一个阶段刚开始觉得终端里直接对话写代码很新鲜用了两周之后发现每次都要重复输入一大段提示词比如“帮我审查这段代码的安全问题”“把这个函数拆成更小的单元”“给这个模块补上单元测试”每次都得重新组织语言效率其实没比手动写快多少。我大概在第三周的时候开始受不了这件事于是花了一个周末把日常最高频的操作整理成了 10 个中文命令封装进 Claude Code 的自定义命令体系里。现在我的日常操作变成了输入/审查、/测试、/重构这样的短命令后面跟上文件路径或者直接留空让它读上下文整个交互路径缩短了至少一半。这套东西的核心价值不在于技术有多复杂而在于它把“提示词工程”从每次手动输入变成了一次性配置。你可以把它理解成给 Claude Code 装了一套中文快捷键——底层还是那些提示词但调用方式从“每次重新说一遍”变成了“喊一个名字就行”。适合谁用我觉得三类人最需要一是每天用 Claude Code 超过两小时的深度用户二是团队里需要统一代码审查和测试规范的技术负责人三是刚接触 AI 编程工具、还不知道怎么组织提示词的新手。下面我会把这 10 个命令的设计思路、具体配置、踩过的坑和实际效果全部拆开讲清楚。2. 整体设计思路与命令体系拆解2.1 为什么选择自定义命令而不是别名或脚本Claude Code 本身支持在项目根目录的.claude/commands/文件夹下放置 Markdown 文件来定义自定义命令每个文件对应一个/命令名。这个机制的好处是命令内容可以写得很长、很结构化而且支持$ARGUMENTS占位符来接收用户输入。我试过用 shell alias 来做类似的事但 alias 没法把多行提示词优雅地传给 Claude Code 的交互界面而且 alias 在不同终端会话之间不共享换台机器就得重新配。自定义命令文件跟着项目走提交到 Git 之后团队成员拉下来就能用这是 alias 做不到的。另一个考虑是命令的可维护性。提示词是需要迭代的——你发现某个审查命令总是漏掉某类问题直接改 Markdown 文件就行改完立即生效不需要重启任何东西。如果用脚本封装每次调整都得改代码、测试、重新部署反馈循环太长了。所以最终方案就是每个命令一个 Markdown 文件放在.claude/commands/下用中文命名内容用中文写调用时直接输入/命令名。2.2 10 个命令的分类逻辑我把这 10 个命令分成了四组分组依据是使用频率和操作对象的不同。第一组是代码质量类包括/审查、/重构、/测试这三个是我每天都会用到的操作对象是具体文件或代码片段。第二组是理解类包括/解释、/架构、/依赖主要用于接手新项目或者阅读不熟悉的代码库。第三组是文档类包括/注释、/文档用来补全代码注释和生成模块说明。第四组是辅助类包括/提交、/排查分别用于生成规范的 Git 提交信息和辅助定位 bug。这个分类不是拍脑袋定的而是我统计了自己两周内所有 Claude Code 交互记录之后归纳出来的。统计结果显示代码审查和测试相关的交互占了 47%理解代码占 23%文档占 18%其他占 12%。所以命令的设计权重也大致按照这个比例来分配——高频操作做得更精细低频操作保持简洁。2.3 命令文件的基本结构每个命令文件的结构其实很固定我总结了一个模板--- description: 一句话说明这个命令做什么 --- 你是一位资深的[角色]。请对以下内容执行[操作] $ARGUMENTS 具体要求 1. [要求一] 2. [要求二] 3. [要求三] 输出格式 - [格式说明]description字段会显示在 Claude Code 的命令提示里方便你忘记命令名的时候快速查找。$ARGUMENTS是用户输入的内容可以是一个文件路径、一段代码或者什么都不传。如果什么都不传我会在提示词里加一句“如果没有提供具体内容请读取当前打开的文件或最近修改的文件”这样命令的容错性会好很多。注意命令文件名就是调用名中文文件名在 macOS 和 Linux 下都没问题但在某些 Windows 终端里可能会有编码问题。如果你用 Windows建议用拼音或者英文命名文件但在文件内容里保持中文提示词。3. 核心命令的详细配置与实操要点3.1 代码审查命令/审查的完整配置这个命令是我用得最多的平均每天调用 8 到 10 次。它的核心设计目标是不只是找语法错误而是从安全、性能、可维护性三个维度给出可操作的修改建议。下面是我最终的配置内容--- description: 对指定代码进行安全、性能、可维护性三维审查 --- 你是一位有十年经验的资深工程师擅长代码审查。请对以下代码进行审查 $ARGUMENTS 审查维度 1. 安全性检查注入风险、边界条件、错误处理是否完备 2. 性能检查不必要的循环、重复计算、内存泄漏风险 3. 可维护性检查命名规范、函数长度、耦合度、注释完整性 输出要求 - 按严重程度分级阻断、警告、建议 - 每个问题给出具体行号和修改方案 - 如果代码没有问题明确说“未发现明显问题” - 最后给出一个总体评分1-10分这个配置我迭代了大概五版。第一版只写了“请审查代码”结果 Claude 返回的内容非常泛全是“建议添加注释”“注意错误处理”这种正确的废话。第二版加了三个维度好了一些但还是不够具体。第三版加了“给出具体行号和修改方案”这才真正变得可操作。第四版加了分级方便我快速判断哪些必须改、哪些可以缓一缓。第五版加了评分纯粹是因为我喜欢有个量化的参考。实际使用的时候我通常这样调用/审查 src/services/payment.ts或者直接在编辑器里选中一段代码然后输入/审查Claude Code 会自动读取选中的内容。实测下来一个 200 行左右的 TypeScript 文件审查时间大约 15 到 20 秒返回的问题列表通常在 5 到 12 条之间其中真正需要立即处理的大概 2 到 4 条。3.2 测试生成命令/测试的参数设计测试生成是第二高频的命令。这个命令的难点在于不同项目用的测试框架不一样Jest、Vitest、Pytest、Go testing 的写法差异很大。我的解决方案是在命令里让 Claude 先检测项目使用的测试框架然后再生成对应风格的测试代码。--- description: 为指定代码生成单元测试 --- 你是一位测试工程师。请为以下代码生成单元测试 $ARGUMENTS 执行步骤 1. 先检测项目使用的测试框架查看 package.json、pyproject.toml 或 go.mod 2. 按照该框架的惯例生成测试代码 3. 覆盖正常路径、边界条件、异常路径三类场景 4. 每个测试用例要有清晰的描述性名称 输出要求 - 直接输出可运行的测试文件内容 - 如果原代码有未导出的函数说明需要如何调整导出方式 - 标注哪些测试用例是必须的哪些是锦上添花这里有个细节值得展开说我特意加了“先检测项目使用的测试框架”这一步。早期版本没有这一步结果在一个用 Vitest 的项目里生成了 Jest 风格的代码虽然大部分 API 兼容但vi.mock和jest.mock的差异还是导致测试跑不起来。加了检测步骤之后这个问题就没再出现过。另一个经验是“标注哪些测试用例是必须的”。Claude 有时候会生成 20 个测试用例其中一半是在测试 getter 和 setter 这种没什么价值的东西。加了这条要求之后它会明确区分核心逻辑测试和边缘测试我通常只保留核心的那部分测试文件不会过于臃肿。3.3 代码解释命令/解释的受众适配/解释这个命令看起来简单但其实最考验提示词设计。因为“解释代码”这四个字太宽泛了Claude 可能给你逐行翻译也可能给你讲设计模式完全取决于它当时的心情。我的做法是在命令里明确指定解释的层次和受众。--- description: 分层解释代码从整体到细节 --- 请按以下层次解释这段代码 $ARGUMENTS 解释层次 1. 一句话概括这段代码做什么 2. 整体流程按执行顺序说明主要步骤 3. 关键细节解释不直观的实现、算法选择、边界处理 4. 潜在问题指出可能存在的隐患或改进空间 受众设定有两年经验的开发者熟悉基本语法但不了解这个项目的业务背景。“受众设定”这一行是点睛之笔。没有它的时候Claude 要么解释得太浅“这是一个函数它接收参数并返回结果”要么太深直接开始讲设计模式的历史演变。加上“有两年经验的开发者”这个设定之后解释的颗粒度就刚刚好——不会假设你什么都不懂也不会假设你什么都懂。3.4 重构命令/重构的约束条件重构命令是最容易出问题的因为“重构”这个词太自由了Claude 可能把你的代码改得面目全非。我的策略是加约束明确重构的目标和边界。--- description: 在保持行为不变的前提下重构代码 --- 请重构以下代码 $ARGUMENTS 重构原则 1. 保持外部行为完全不变不改变函数签名和返回值 2. 优先消除重复代码和过深的嵌套 3. 单个函数不超过 30 行 4. 不引入新的外部依赖 输出要求 - 先说明重构前后的主要变化 - 输出完整的重构后代码 - 标注哪些改动是安全的哪些需要额外测试验证“不引入新的外部依赖”这条很重要。有一次我让它重构一个工具函数它给我引入了 lodash理由是“用_.debounce更简洁”。但我的项目本身没有 lodash为了一个函数引入整个库完全不划算。加了这条约束之后它就会用原生方法实现了。“标注哪些改动是安全的”这条也很实用。重构最怕的是改出 bug有了这个标注我可以优先验证那些“需要额外测试”的部分安全的改动直接信任。4. 完整实操流程从零搭建这套工作流4.1 环境准备与目录结构假设你已经安装好了 Claude Code安装过程不展开官方文档写得很清楚接下来就是在项目根目录创建命令文件夹。我建议的做法是在项目根目录执行mkdir -p .claude/commands然后在这个目录下创建 10 个 Markdown 文件。文件名就是命令名比如审查.md、测试.md、重构.md。这里有个小技巧如果你想让命令支持子分类可以创建子文件夹比如.claude/commands/code/审查.md调用的时候就是/code:审查。我一开始用了子分类后来发现多打几个字符反而降低了效率就全部改成平铺了。目录结构最终长这样项目根目录/ ├── .claude/ │ └── commands/ │ ├── 审查.md │ ├── 测试.md │ ├── 重构.md │ ├── 解释.md │ ├── 架构.md │ ├── 依赖.md │ ├── 注释.md │ ├── 文档.md │ ├── 提交.md │ └── 排查.md ├── src/ └── ...提示.claude/commands/目录建议提交到 Git这样团队成员拉取代码后自动获得这套命令。但如果你在命令里写了项目相关的敏感信息比如内部 API 地址就要谨慎处理了。4.2 命令文件的批量创建方法手动创建 10 个文件有点繁琐我写了一个 shell 脚本一次性生成所有文件的骨架然后逐个填充内容。脚本大概长这样#!/bin/bash commands(审查 测试 重构 解释 架构 依赖 注释 文档 提交 排查) for cmd in ${commands[]}; do cat .claude/commands/${cmd}.md EOF --- description: ${cmd}命令的说明 --- 请对以下内容执行${cmd}操作 \$ARGUMENTS 具体要求 1. 待补充 2. 待补充 EOF done跑完这个脚本之后10 个骨架文件就都有了接下来只需要逐个打开、把“待补充”替换成实际内容。这个方法比手动创建快很多而且不容易漏掉某个命令。4.3 验证命令是否生效创建完文件之后在 Claude Code 里输入/应该就能看到命令列表里出现了这些中文命令。如果没看到检查两个地方一是文件是否确实放在了.claude/commands/目录下二是文件扩展名是否是.md。我遇到过一个问题在 Windows 上用记事本创建文件保存成了.md.txt导致命令不识别。后来统一用 VS Code 创建文件就没这个问题了。验证单个命令是否正常工作可以输入/审查然后跟一个简单的测试文件路径。如果 Claude 返回了结构化的审查结果说明命令生效了。如果它只是回复“请提供要审查的代码”说明$ARGUMENTS没有被正确替换检查一下命令文件里是否写了$ARGUMENTS这个占位符。4.4 实际使用中的调用模式经过一个月的使用我总结出了几种最高效的调用模式。第一种是“文件路径模式”直接在命令后面跟文件路径适合审查整个文件或生成整个文件的测试。第二种是“选中模式”在编辑器里选中一段代码然后调用命令Claude 会自动读取选中内容适合针对特定函数进行操作。第三种是“上下文模式”不传任何参数让 Claude 读取最近修改的文件适合在刚写完代码后立即审查。这三种模式的效率差异很明显。文件路径模式最精确但需要输入路径选中模式最快但需要鼠标操作上下文模式最省事但有时候 Claude 会读错文件。我的习惯是小范围修改用选中模式整个文件操作用路径模式批量处理用上下文模式。5. 常见问题与排查技巧实录5.1 命令不生效的几种原因最常见的问题是命令文件放错了位置。Claude Code 只会读取项目根目录下的.claude/commands/如果你放在用户主目录的.claude/commands/下那是全局命令所有项目都能用但优先级低于项目级命令。我有一次在项目里创建了/审查但全局也有一个同名的结果调用的时候走了全局版本行为不一致排查了半天才发现是优先级问题。第二个常见问题是文件编码。中文命令名和中文内容都要求文件是 UTF-8 编码。如果你在 Windows 上用默认的 GBK 编码保存Claude Code 读取的时候会乱码命令名显示不出来。解决方法很简单用 VS Code 打开文件右下角点击编码选择“通过编码保存”然后选 UTF-8。第三个问题是$ARGUMENTS写错了。正确的写法就是$ARGUMENTS全大写前面一个美元符号。我见过有人写成$ARGUMENT少了个 S或者$arguments小写都不会被替换。5.2 命令输出质量不稳定的调优方法即使命令文件写好了Claude 的输出质量也可能时好时坏。我总结了几个调优方向。第一个是增加“反面示例”比如在审查命令里加一句“不要输出‘建议添加更多注释’这类泛泛而谈的内容”这样能有效减少废话。第二个是明确输出格式用列表还是表格用中文还是英文都要写清楚。第三个是限制输出长度比如“最多列出 10 个问题按严重程度排序”避免它生成一篇论文。还有一个技巧是“分步执行”。对于复杂的命令不要让它一步到位而是拆成两步。比如/重构命令我有时候会先让它“列出重构方案”确认方案合理之后再让它“按照方案执行重构”。这样虽然多了一次交互但重构结果的可控性大大提升。5.3 中文命令的兼容性注意事项中文命令在大部分终端里都没问题但有几个场景需要留意。一是在 CI/CD 流水线里调用 Claude Code 的时候如果环境变量LANG没有设置为 UTF-8中文命令可能无法识别。解决方法是在流水线脚本里加一行export LANGen_US.UTF-8或者export LANGzh_CN.UTF-8。二是在某些 SSH 客户端里中文输入和显示可能有问题这个跟客户端配置有关跟 Claude Code 本身无关。另外中文命令名在 Tab 补全的时候可能不如英文方便。我的折中方案是命令文件名用中文但在命令文件的description里加上拼音缩写比如description: 代码审查 (shencha)这样输入/shen的时候也能通过描述匹配到。5.4 常见问题速查表问题现象可能原因解决方法输入/看不到中文命令文件不在.claude/commands/下确认目录位置项目级命令必须在项目根目录命令名显示乱码文件编码不是 UTF-8用 VS Code 重新以 UTF-8 保存$ARGUMENTS没有被替换占位符拼写错误检查是否写成了$ARGUMENTS全大写命令输出太泛提示词约束不够增加反面示例和输出格式要求重构后代码行为改变缺少行为不变约束在命令里明确“保持外部行为不变”测试代码跑不起来测试框架不匹配增加“先检测测试框架”步骤命令执行超时输入内容太长拆分文件分多次审查6. 这套工作流带来的实际变化与扩展思路用了这套中文命令工作流一个月之后我统计了一下数据平均每次代码审查的时间从原来的 8 分钟包括组织提示词、等待响应、理解输出降到了 3 分钟左右测试生成的时间从 15 分钟降到了 6 分钟。更重要的是因为调用成本降低了我变得更愿意频繁地做代码审查——以前可能写完一个模块才审查一次现在每写完一个函数就顺手/审查一下问题发现得更早修复成本也更低。这套东西的扩展性其实很好。我现在正在尝试的方向是把团队内部的代码规范也写进命令里比如命名规范、日志格式、错误码规范这样新成员拉下代码后用/审查就能按照团队标准来检查。另一个方向是给不同的项目定制不同的命令集比如前端项目有一套/组件审查、/样式检查后端项目有一套/接口审查、/性能分析通过项目级的.claude/commands/目录来隔离。最后分享一个我踩过的坑不要一次性把 10 个命令都写得很复杂。我一开始每个命令都写了 50 行以上的提示词结果发现很多命令一周都用不到一次维护成本却很高。后来我把低频命令简化到 10 行以内只保留最核心的指令高频命令才做精细打磨。这个“二八原则”在命令设计上同样适用——把 80% 的精力花在 20% 最高频的命令上整体效率提升最明显。