1. 为什么我要给 Claude Code 装一套中文命令
用 Claude Code 写代码这件事，我从它刚开放命令行版本就开始折腾了。最开始那阵子，我每天的工作流大概是这样的：打开终端，敲claude，然后用英文跟它描述需求，比如“refactor this function to use async/await”，或者“add error handling to the fetch call”。能用，但总觉得哪里别扭。问题不在于 Claude 的英文理解能力，而在于我自己的表达效率——用非母语描述复杂需求时，脑子里的想法到指尖的英文之间，总有一层翻译损耗。
这个损耗在简单任务上不明显，但在复杂场景下会被放大。比如我想让它“把这个模块的错误处理统一成 Result 类型，顺便把日志级别从 debug 调到 warn，但保留第三方库调用处的 debug 日志”，用英文说一遍，我得在脑子里先组织语法，再检查用词是否准确，最后才敲出去。整个过程可能多花十几秒，而且有时候表达不精确，Claude 理解偏了，还得重新解释。一天下来，这种微小的摩擦累积起来，对心流状态的破坏是实实在在的。
所以我开始琢磨一件事：能不能把常用的操作封装成中文命令，让 Claude Code 直接识别？这样我只需要敲/审查或者/重构，后面跟一句中文描述，就能触发对应的行为。这个想法听起来简单，但实现过程中踩了不少坑，也积累了一些经验。这篇文章就是把这套工作流包的完整搭建过程拆开来讲，包括设计思路、具体实现、参数配置、常见问题排查，以及我在实际使用中总结出来的一些技巧。
这套东西适合谁呢？如果你已经在用 Claude Code 或者类似的 CLI 编程工具，并且日常工作中需要频繁跟 AI 交互来完成编码任务，那这套中文命令工作流能帮你省下不少切换成本。如果你还没开始用 Claude Code，也没关系，文章里会涉及安装配置的基础内容，你可以跟着一步步来。核心思路是通用的，换成其他 CLI 工具也能借鉴。
2. 整体设计思路与方案选型
2.1 为什么选择自定义命令而不是提示词模板
最开始我尝试的是提示词模板方案。具体做法是在项目根目录放一个prompts.md文件，里面写好各种场景的提示词，用的时候复制粘贴。这个方法用了大概一周，问题就暴露出来了：复制粘贴本身就是一个打断动作，而且模板文件越来越长，找起来费劲。更重要的是，Claude Code 的交互是流式的，你粘贴一大段提示词进去，它开始执行，但如果你想在中间调整参数，比如换个文件路径或者改个约束条件，就得重新来一遍。
后来我转向了 Claude Code 的自定义命令功能。这个功能允许你在~/.claude/commands/目录下放置 Markdown 文件，每个文件对应一个命令。文件名就是命令名，文件内容就是提示词模板。使用时输入/命令名，Claude Code 会自动加载对应的提示词并执行。这个机制的好处是：命令是持久化的，不需要每次复制粘贴；命令可以带参数，通过$ARGUMENTS占位符接收；命令文件本身是 Markdown，写起来很自然。
选择这个方案还有一个考虑：Claude Code 的命令系统支持嵌套和组合。你可以在一个命令里引用另一个命令的输出，或者把多个命令串起来用。这为后面构建复杂工作流打下了基础。
2.2 十个命令的选取逻辑
我最终确定了十个命令，覆盖了日常编码中最频繁的场景。选取逻辑是这样的：先统计我自己一周内跟 Claude Code 的交互记录，把最常见的请求类型归类，然后为每一类设计一个命令。具体分类如下：
| 命令名 | 功能定位 | 使用频率 |
|---|---|---|
/审查 | 代码审查，检查潜在问题 | 每天多次 |
/重构 | 重构指定代码块 | 每天多次 |
/解释 | 解释代码逻辑 | 每天几次 |
/测试 | 生成单元测试 | 每天几次 |
/优化 | 性能优化建议 | 每周几次 |
/文档 | 生成注释和文档 | 每周几次 |
/调试 | 辅助排查 bug | 每周几次 |
/转换 | 语言或框架转换 | 每周几次 |
/提交 | 生成 commit message | 每天多次 |
/学习 | 解释新技术概念 | 每周几次 |
这十个命令基本覆盖了我 90% 以上的交互场景。每个命令的提示词都经过反复调整，确保输出质量稳定。比如/审查命令，我一开始只写了“审查这段代码”，结果 Claude 的审查很泛泛，只说“看起来不错”或者“可以考虑加个错误处理”。后来我逐步细化了审查维度：安全性、性能、可读性、边界条件、错误处理，每个维度都给出具体的检查点。调整之后，审查质量明显提升。
2.3 命令文件的结构设计
每个命令文件的结构我统一成了三段式：角色设定、任务描述、输出格式。角色设定让 Claude 进入特定的思维模式，比如/审查命令的角色设定是“你是一位有十年经验的资深工程师，擅长发现代码中的潜在问题”。任务描述具体说明要做什么，包括输入参数的处理。输出格式规定结果的呈现方式，比如用表格还是列表，是否需要给出修改建议。
这个结构不是拍脑袋定的，而是试出来的。最开始我只写任务描述，发现 Claude 的输出风格飘忽不定，有时候很详细，有时候很简略。加上角色设定后，输出的专业度和一致性明显改善。输出格式的约束则让结果更易读，方便我快速扫一眼就抓住重点。
3. 核心命令的详细拆解与配置要点
3.1/审查命令：让代码审查有章可循
/审查是我用得最多的命令，平均每天要跑七八次。它的提示词文件放在~/.claude/commands/审查.md，内容大致是这样的：
你是一位有十年经验的资深工程师，擅长发现代码中的潜在问题。 请审查以下代码，从五个维度进行分析： 1. 安全性：是否存在注入、越权、敏感信息泄露等风险 2. 性能：是否有不必要的循环、重复计算、内存泄漏隐患 3. 可读性：命名是否清晰、逻辑是否直观、注释是否充分 4. 边界条件：空值、极值、并发场景是否处理妥当 5. 错误处理：异常是否捕获、错误信息是否有用、恢复策略是否合理 对每个发现的问题，给出： - 问题描述 - 严重程度（高/中/低） - 修改建议（附代码示例） 如果某个维度没有问题，明确说“未发现明显问题”。 代码： $ARGUMENTS这个提示词的关键在于“五个维度”的设定。没有这个框架，Claude 的审查是发散的，可能只关注它觉得重要的点。有了框架之后，审查变得系统化，每次都能覆盖到所有关键方面。另外“严重程度”的标注也很重要，它帮我快速判断哪些问题必须马上修，哪些可以后面再说。
实际使用时的命令格式是：/审查 src/utils/parser.js。Claude 会读取文件内容，然后按照五个维度输出审查结果。如果我想审查一段选中的代码而不是整个文件，可以直接把代码粘贴在命令后面。
注意：
/审查命令默认会读取文件全文。如果文件很大，比如超过 500 行，建议先用/解释命令了解结构，再针对关键部分做审查。否则 Claude 的上下文窗口可能被占满，影响审查深度。
3.2/重构命令：带约束的重构指令
重构是另一个高频操作。我的/重构命令和普通的“帮我重构这段代码”最大的区别在于：它强制要求 Claude 说明重构的理由和影响范围。提示词里明确写了：
你是一位注重代码质量的资深工程师。 请对以下代码进行重构，要求： 1. 保持功能不变，不引入新的 bug 2. 提升可读性和可维护性 3. 如果涉及性能优化，说明优化前后的复杂度变化 4. 列出所有修改点，每个修改点说明理由 5. 指出重构可能影响到的其他模块 重构后的代码放在代码块中，修改说明放在代码块之前。 代码： $ARGUMENTS这个命令的“列出所有修改点”要求很关键。早期版本没有这一条，Claude 直接给出一版重构后的代码，我看半天才能理解它改了什么。加上修改点列表后，我可以快速扫一眼就知道这次重构的幅度和重点，决定是否采纳。
还有一个细节：我要求“重构后的代码放在代码块中，修改说明放在代码块之前”。这个顺序很重要，因为如果说明放在后面，我得先看完代码才能看到解释，阅读体验不好。说明在前，我可以先判断这次重构是否符合预期，再决定要不要细看代码。
3.3/测试命令：生成可运行的测试用例
生成单元测试这件事，Claude 默认做得不错，但有几个常见问题：测试用例覆盖不全、断言太弱、没有考虑边界条件。我的/测试命令针对这几点做了约束：
你是一位测试驱动开发专家。 请为以下代码生成单元测试，要求： 1. 覆盖正常路径、边界条件、异常路径 2. 每个测试用例有明确的断言 3. 使用项目现有的测试框架（根据文件扩展名判断） 4. 测试用例命名清晰，能看出测试意图 5. 如果发现代码本身难以测试，指出原因并给出改进建议 代码： $ARGUMENTS“使用项目现有的测试框架”这一条是通过文件扩展名来判断的。如果是.js文件，默认用 Jest；如果是.py文件，默认用 pytest；如果是.go文件，默认用标准库的 testing 包。这个判断逻辑写在提示词里，Claude 会根据文件类型自动选择。
“如果发现代码本身难以测试，指出原因并给出改进建议”这一条是我后来加的。有些代码耦合度太高，或者依赖外部服务，测试写起来很别扭。与其硬写一堆 mock，不如让 Claude 指出设计问题，从根源上改进。
3.4/提交命令：规范 commit message
/提交命令看起来简单，但用好了能省不少事。我的提示词是这样的：
请根据以下 git diff 生成 commit message，遵循 Conventional Commits 规范。 格式：<type>(<scope>): <subject> type 可选：feat, fix, docs, style, refactor, test, chore scope 可选：根据修改的文件路径推断 subject 用中文描述，不超过 50 字 如果修改涉及多个不相关的变更，建议拆分成多个 commit。 diff： $ARGUMENTS这个命令的使用方式是：先git diff --staged查看暂存区的改动，然后把输出粘贴到命令后面。Claude 会生成符合规范的 commit message。如果改动涉及多个不相关的变更，它会建议拆分，并给出每个 commit 的 message。
实操心得：我习惯在
git add之后先跑一遍/提交，看看 Claude 怎么理解这次改动。有时候它的理解和我原本的意图不一致，这往往说明我的改动太杂了，应该拆成更小的提交。这个习惯帮我避免了很多“大杂烩”式的 commit。
3.5/调试命令：系统化排查问题
调试命令的设计思路和前面几个不太一样。调试是一个交互过程，很难用一段静态提示词搞定。我的做法是把/调试命令设计成一个“排查框架”，引导 Claude 按照固定步骤来分析问题：
你是一位擅长排查疑难问题的工程师。 请按照以下步骤分析这个 bug： 1. 复现条件：什么情况下会触发这个问题 2. 可能原因：列出所有可能的原因，按可能性排序 3. 排查方法：针对每个原因，给出具体的排查步骤 4. 验证方案：如何确认问题是否解决 5. 预防措施：如何避免类似问题再次发生 问题描述： $ARGUMENTS这个框架的价值在于它强迫 Claude 不要直接跳到“解决方案”，而是先做完整的分析。实际使用中，我经常发现 Claude 在“可能原因”这一步就找到了真正的问题，根本不需要走到“排查方法”。而且“预防措施”这一步往往能发现一些设计层面的改进点。
4. 完整实操流程与配置细节
4.1 环境准备与 Claude Code 安装
在开始配置命令之前，需要先确保 Claude Code 已经正确安装。安装方式取决于操作系统，我分别在 macOS 和 Ubuntu 上装过，流程略有不同。
macOS 上最简单的方式是通过 npm 全局安装：
npm install -g @anthropic-ai/claude-code安装完成后，运行claude --version确认版本。如果提示找不到命令，检查 npm 全局 bin 目录是否在 PATH 中。通常需要把~/.npm-global/bin或者/usr/local/bin加到 PATH 里。
Ubuntu 上的流程类似，但可能会遇到权限问题。如果 npm 全局安装报错EACCES，不要用sudo硬装，而是先配置 npm 的全局目录：
mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' export PATH=~/.npm-global/bin:$PATH把最后一行加到~/.bashrc或~/.zshrc里，然后重新加载配置文件。这样安装的包都在用户目录下，不需要 root 权限。
安装完成后，第一次运行claude会引导你完成登录和初始化配置。按照提示操作即可。如果遇到auto-update failed: no write permission to npm prefix这类报错，说明 npm 全局目录没有写权限，用上面的方法重新配置一下就好。
4.2 命令目录的创建与文件组织
Claude Code 的自定义命令存放在~/.claude/commands/目录下。如果这个目录不存在，手动创建：
mkdir -p ~/.claude/commands然后为每个命令创建一个 Markdown 文件。文件名就是命令名，比如审查.md对应/审查命令。注意文件名不要有空格，中文文件名是支持的，但为了兼容性，建议用简洁的中文词。
我的目录结构是这样的：
~/.claude/commands/ ├── 审查.md ├── 重构.md ├── 解释.md ├── 测试.md ├── 优化.md ├── 文档.md ├── 调试.md ├── 转换.md ├── 提交.md └── 学习.md每个文件的内容就是前面介绍的提示词模板。写完之后不需要重启 Claude Code，直接在会话里输入/审查就能用。如果命令没有生效，检查文件名是否正确，以及文件是否保存在正确的目录下。
4.3 参数传递与动态内容处理
Claude Code 的命令支持通过$ARGUMENTS占位符接收参数。使用时，命令后面的所有内容都会替换到$ARGUMENTS的位置。比如/审查 src/index.js，Claude 收到的提示词就是“请审查以下代码...代码：src/index.js”。
这里有一个细节需要注意：$ARGUMENTS替换的是原始文本，Claude 需要自己判断这是文件路径还是代码片段。如果传的是文件路径，Claude 会尝试读取文件；如果传的是代码片段，它会直接分析。这个判断有时候会出错，比如路径名恰好看起来像代码。为了避免歧义，我养成了一个习惯：传文件路径时用反引号包起来，比如/审查 \src/index.js``。这样 Claude 能更准确地识别。
如果命令需要多个参数，可以用$1、$2这样的位置参数。不过 Claude Code 对位置参数的支持不如$ARGUMENTS稳定，我一般尽量用$ARGUMENTS接收全部内容，然后在提示词里说明如何解析。
4.4 命令的组合与嵌套使用
单个命令用熟了之后，可以尝试组合使用。比如先/解释理解代码逻辑，再/重构改进代码，最后/测试生成测试用例。这三个命令串起来，就是一个完整的代码改进流程。
Claude Code 本身不提供命令串联的语法，但可以通过在提示词里引用其他命令的输出实现类似效果。比如在/重构命令的提示词里加一句“参考之前/审查命令的输出”，Claude 会尝试从上下文中找到审查结果。不过这种方式依赖上下文窗口的大小，如果对话太长，早期内容可能被截断。
更可靠的做法是把上一个命令的输出保存到文件，然后在下一个命令里引用文件路径。比如：
# 先审查，把结果保存到文件 /审查 src/index.js > review.md # 再重构，引用审查结果 /重构 参考 review.md 中的审查意见，重构 src/index.js这种方式虽然多了一步手动操作，但结果更可控，适合处理复杂任务。
5. 常见问题与排查技巧实录
5.1 命令不生效或报错
最常见的问题是命令输入后没有反应，或者提示“未知命令”。排查步骤是这样的：首先确认文件确实在~/.claude/commands/目录下，用ls ~/.claude/commands/查看。其次检查文件名是否和输入的命令名完全一致，包括大小写。中文命令名对大小写不敏感，但英文命令名是敏感的。最后确认文件内容不为空，且是合法的 Markdown 格式。
如果命令能识别但执行报错，通常是提示词里的$ARGUMENTS没有被正确替换。检查命令后面是否跟了参数，如果没跟参数，$ARGUMENTS会是空字符串，Claude 可能不知道要处理什么。这种情况下，可以在提示词里加一个默认值处理，比如“如果 $ARGUMENTS 为空，提示用户输入代码或文件路径”。
5.2 输出质量不稳定的应对
即使提示词写得很详细，Claude 的输出质量偶尔还是会波动。同一个/审查命令，有时候给出很深入的分析，有时候只是泛泛而谈。这种波动主要受两个因素影响：上下文长度和模型状态。
上下文长度方面，如果当前会话已经进行了很多轮对话，早期内容会占用上下文窗口，导致 Claude 对当前命令的注意力下降。解决办法是定期开启新会话，或者在执行重要命令前用/compact压缩上下文。Claude Code 的/compact命令可以把之前的对话总结成简短摘要，释放上下文空间。
模型状态方面，这个不太好控制，但可以通过调整提示词来缓解。我的经验是，在提示词里加入具体的示例，能显著提升输出稳定性。比如/审查命令里，我会给一个“好的审查结果”的示例，展示期望的输出格式和深度。Claude 看到示例后，会倾向于模仿这个风格。
5.3 中文命令的编码问题
中文文件名和中文内容在大多数系统上没问题，但在某些环境下可能会遇到编码错误。如果 Claude Code 读取命令文件时报编码错误，检查文件是否保存为 UTF-8 格式。用file 审查.md命令可以查看文件编码，如果是 ISO-8859 或 GBK，用iconv转换：
iconv -f GBK -t UTF-8 审查.md > 审查_utf8.md mv 审查_utf8.md 审查.md另外，如果终端本身的编码不是 UTF-8，中文命令名可能显示为乱码。检查locale命令的输出，确保LANG和LC_ALL包含 UTF-8。在~/.bashrc里加上export LANG=en_US.UTF-8可以解决大部分问题。
5.4 命令冲突与优先级
如果你安装了多个 Claude Code 插件或者配置了多个命令目录，可能会出现命令名冲突。Claude Code 的命令查找顺序是：项目目录下的.claude/commands/优先于用户目录下的~/.claude/commands/。如果两个目录下有同名命令，项目目录的会覆盖用户目录的。
这个机制可以用来做项目特定的命令覆盖。比如某个项目需要特殊的审查规则，可以在项目的.claude/commands/下放一个审查.md，覆盖全局的审查命令。不过要注意，项目目录下的命令文件需要提交到版本控制，否则其他协作者用不了。
5.5 性能优化与响应速度
命令执行速度主要受两个因素影响：提示词长度和文件读取量。提示词越长，Claude 处理时间越久。我的经验是，单个命令的提示词控制在 500 字以内比较合适，超过 1000 字就会明显变慢。如果提示词确实需要很长，考虑拆分成多个命令，或者把不常变的部分抽成共享的引用文件。
文件读取量方面，如果/审查命令读取了一个 2000 行的文件，Claude 需要先解析整个文件再分析，速度会慢很多。对于大文件，建议先用/解释了解结构，然后针对关键函数或模块做审查。或者用sed -n '100,200p' file.js提取特定行范围，再传给审查命令。
6. 进阶技巧与工作流扩展
6.1 为不同项目定制命令变体
全局命令适合通用场景，但不同项目有不同的技术栈和规范。比如前端项目可能更关注组件拆分和状态管理，后端项目更关注事务处理和并发安全。我通常会在项目根目录的.claude/commands/下放几个项目特定的命令变体。
以 React 项目为例，我会加一个/组件审查命令，专门检查组件的 props 类型、副作用清理、渲染性能等问题。提示词里会引用项目的 ESLint 配置和组件规范文档，让审查更贴合项目实际。
6.2 结合 Git Hooks 自动触发
Claude Code 的命令是手动触发的，但有些场景适合自动化。比如每次 commit 之前自动跑一遍/审查，把审查结果作为 commit 的参考。这可以通过 Git Hooks 实现。
在.git/hooks/pre-commit里加一段脚本，调用 Claude Code 执行审查命令，把结果输出到终端。如果审查发现严重问题，可以阻止 commit。不过这个方案有个缺点：Claude Code 的启动和响应需要时间，每次 commit 都等几秒到十几秒，体验不太好。我的做法是只在手动触发时跑审查，不强制加到 pre-commit 里。
6.3 命令输出的后处理
Claude 的输出有时候需要进一步处理才能用。比如/测试生成的测试代码，可能需要调整 import 路径或者格式化。我写了一个简单的 shell 函数，把 Claude 的输出通过管道传给prettier或gofmt，自动格式化后再保存到文件。
claude_test() { claude "/测试 $1" | sed -n '/```/,$p' | sed '1d;$d' | prettier --parser babel }这个函数提取 Claude 输出中的代码块，去掉 Markdown 标记，然后用 prettier 格式化。虽然简单，但省去了手动复制粘贴和格式调整的步骤。
6.4 多模型切换与命令适配
Claude Code 支持切换不同的模型，不同模型的输出风格和能力有差异。我的经验是，复杂重构和深度审查用能力更强的模型，简单的解释和文档生成用轻量模型。可以在命令提示词里加一句“如果当前模型是轻量版，请简化输出”，让命令自适应。
另外，如果你同时用 Codex CLI 或其他 AI 编程工具，可以把这套中文命令的思路迁移过去。核心逻辑是一样的：把高频操作封装成可复用的提示词模板，通过命令系统快速调用。不同工具的命令语法可能不同，但设计思路是通用的。
6.5 命令库的版本管理与分享
这套命令文件我放在一个 Git 仓库里管理，方便同步到不同机器。仓库结构很简单，就是commands/目录下的十个 Markdown 文件，加上一个README.md说明每个命令的用途和用法。
分享给团队成员时，他们只需要把仓库 clone 下来，然后把commands/目录软链接到~/.claude/commands/即可：
ln -s /path/to/command-repo/commands ~/.claude/commands这样更新命令库时，所有人同步 pull 一下就能拿到最新版本。如果团队有特殊的审查规则或编码规范，可以在仓库里加一个CONTRIBUTING.md，说明如何修改和扩展命令。
7. 我踩过的坑与实测有效的经验
第一个坑是命令名太短导致误触发。我一开始把审查命令命名为/查，结果在正常对话中只要提到“查”字，Claude 就可能误以为是命令。后来改成/审查，两个字的命令名既好记又不容易误触发。建议命令名至少两个字，且不要用日常对话中的高频词。
第二个坑是提示词里的示例太具体，导致 Claude 过度模仿。我在/重构命令里放了一个 React 组件的重构示例，结果 Claude 在重构 Python 代码时也试图套用 React 的模式。后来我把示例改成伪代码，只展示结构和格式，不涉及具体技术栈，问题就解决了。
第三个坑是忽略了命令的上下文依赖。有些命令需要知道当前项目的技术栈和规范才能给出好结果。比如/测试命令，如果不告诉 Claude 项目用的是 Jest 还是 Vitest，它可能生成不兼容的测试代码。解决办法是在命令提示词里加一句“先检查 package.json 或 requirements.txt，确定测试框架后再生成代码”。
实测下来最有效的经验是：命令提示词要定期回顾和调整。我每个月会花半小时翻一遍最近的使用记录，看看哪些命令的输出质量下降了，哪些命令很少用可以删掉。这套命令库不是一次写完就固定的，而是随着工作流的变化持续演进的。刚开始可能只有三五个命令，用着用着发现新的高频场景，就加一个新命令进去。慢慢地，这套东西就成了我日常编码中离不开的工具。
