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 LANG=en_US.UTF-8或者export LANG=zh_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% 最高频的命令上，整体效率提升最明显。
