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.jsClaude 收到的提示词就是“请审查以下代码...代码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 LANGen_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确定测试框架后再生成代码”。实测下来最有效的经验是命令提示词要定期回顾和调整。我每个月会花半小时翻一遍最近的使用记录看看哪些命令的输出质量下降了哪些命令很少用可以删掉。这套命令库不是一次写完就固定的而是随着工作流的变化持续演进的。刚开始可能只有三五个命令用着用着发现新的高频场景就加一个新命令进去。慢慢地这套东西就成了我日常编码中离不开的工具。