1. 为什么我要折腾这套中文命令工作流用 Claude Code 做开发的人大概都有个共同感受它本身能力很强但默认的交互方式对中文用户并不算友好。每次开新会话都要重新交代一遍项目背景、代码规范、提交习惯想让它按固定套路做代码审查、写提交信息、生成变更日志又得反复贴提示词。时间一长这些重复劳动比写代码本身还累。我日常的工作流里Claude Code 承担了相当一部分编码、重构和排查任务用得越多越觉得应该把那些高频、固定、可复用的操作沉淀下来。于是就有了这个项目把 10 个中文命令装进 Claude Code做成一套可以直接调用的 AI 编程工作流包。核心思路很简单——用自定义命令custom commands把常用提示词固化成 slash 命令用中文命名让整个交互过程更贴近母语直觉。这套东西解决的不是什么高深问题就是三个字省事、统一、可复用。适合已经在用 Claude Code、Codex CLI 这类命令行 AI 编程工具但还没系统整理过自己工作流的开发者也适合刚上手、想直接抄一套现成配置的新手。下面我把整套设计思路、每个命令的实现细节、踩过的坑以及怎么迁移到其他 CLI 工具完整拆一遍。2. 整体设计思路与命令选型逻辑2.1 为什么选自定义命令而不是提示词模板很多人第一反应是搞一个提示词文档用的时候复制粘贴。我一开始也这么干但很快就放弃了。原因有三个一是复制粘贴有上下文损耗长提示词容易漏段二是提示词散落在笔记软件里找起来费劲三是没法带参数每次都要手动改项目名、文件路径。Claude Code 的自定义命令机制刚好解决这些问题。它允许你在项目或用户目录下放 Markdown 文件文件名就是命令名文件内容就是提示词还支持$ARGUMENTS占位符接收参数。调用时直接敲/命令名 参数干净利落。这比维护一堆提示词片段高效得多而且命令文件本身可以进版本控制团队共享也方便。提示自定义命令分项目级和用户级。项目级放在.claude/commands/下只对当前项目生效用户级放在~/.claude/commands/下全局可用。我建议通用命令放用户级项目专属的放项目级。2.2 10 个命令的选取标准选哪 10 个命令我纠结了挺久。最后定下的标准是高频、边界清晰、输入输出明确、不依赖特定项目结构。按这个标准筛下来覆盖了从代码理解到提交发布的完整链路。命令名用途触发场景/审查代码审查按规范逐条检查提交前、PR 前/提交生成规范的中文提交信息git commit 前/解释逐行解释指定文件或函数接手陌生代码/重构按指定目标重构代码代码异味明显时/测试为指定代码生成单元测试补测试覆盖率/排查根据报错信息定位问题遇到 bug/文档为模块生成中文文档交付、交接/日志根据 git diff 生成变更日志发版前/优化性能与可读性优化建议代码评审/计划把需求拆成可执行任务清单新功能开发前这 10 个命令不是拍脑袋定的是我统计了自己两周内实际调用 AI 编程助手的记录把出现频率最高的操作提炼出来的。你会发现它们有个共同点都是输入明确、输出结构化的任务。像帮我写个功能这种模糊需求就不适合做成固定命令因为每次的上下文差异太大。2.3 中文命名的取舍用中文做命令名是我这套工作流最有争议也最爽的决定。争议在于部分终端对中文输入的支持不够顺滑切换输入法有成本爽在于母语直觉调用记忆负担几乎为零。我的实测结论是在 macOS 的 iTerm2 和 Windows Terminal 下中文命令名输入都没问题Claude Code 也能正确识别。真正需要注意的是文件名编码必须确保是 UTF-8否则在某些系统上会读不到。如果你团队里有人用不惯中文命令完全可以做一套英文别名指向同一份提示词内容这个后面会讲怎么实现。3. 核心命令的提示词设计与实操要点3.1 命令文件的基本结构一个自定义命令文件就是普通的 Markdown但有几个关键点。第一行通常是命令的简短描述Claude Code 会用它做命令列表的说明。正文就是提示词可以用$ARGUMENTS接收调用时传入的参数。以/审查为例文件路径是~/.claude/commands/审查.md内容大致长这样对指定代码进行严格审查按以下维度逐条检查并输出结论。 审查对象$ARGUMENTS 检查维度 1. 命名规范变量、函数、类名是否表意清晰 2. 边界处理空值、越界、异常分支是否覆盖 3. 资源管理文件、连接、锁是否确保释放 4. 并发安全共享状态是否有竞态风险 5. 可读性嵌套层级、函数长度是否合理 输出格式 - 每个维度给出「通过 / 存疑 / 不通过」三档结论 - 存疑和不通过的必须给出具体行号和修改建议 - 最后给一个总体风险等级低 / 中 / 高调用时敲/审查 src/utils/parser.ts它就会按这套维度去查。这里的关键设计是强制结构化输出。如果你只说帮我审查代码AI 会给你一段泛泛而谈的评价但你把维度、档位、输出格式都定死它就只能按框架来结果的可比性和可操作性完全不一样。3.2 参数传递的三种模式$ARGUMENTS是这套工作流的核心机制但用法有讲究。我总结了三种模式对应不同场景。第一种是单参数直传比如/解释 src/core/engine.ts直接把文件路径塞进去。这种最简单适合目标明确的场景。第二种是多参数拼接比如/重构 src/api/user.ts 把回调改成 async/await。这里$ARGUMENTS会接收整串内容提示词里要写清楚怎么拆分。我通常约定第一个空格前是目标后面是要求。第三种是无参数交互比如/计划调用时不带参数提示词里让它先反问需求。这种适合需要多轮澄清的任务。实现方式是在提示词里明确写如果未提供参数先向我提问确认需求不要直接开始。注意$ARGUMENTS不会自动做类型转换或校验传进去什么就是什么。所以提示词里最好加一句如果参数为空或格式不对先提示我补充避免 AI 拿着空参数硬编。3.3 让输出稳定的三个技巧用了一段时间后我发现同样的命令输出质量会波动。有时候很精准有时候跑偏。后来我总结出三个稳定输出的技巧实测有效。技巧一给输出模板。不要只说生成测试而是给出测试文件的结构模板包括 describe 块怎么写、断言风格、mock 方式。AI 有了模板输出就收敛了。技巧二限定范围。明确告诉它只输出代码不要解释或者先给结论再给理由。不加限定的命令AI 倾向于长篇大论反而稀释了有用信息。技巧三要求自检。在提示词末尾加一句输出前自查是否覆盖了所有要求是否有未处理的边界。这一步能让 AI 在生成后再过一遍明显减少遗漏。我做过对比加了自检的命令返工率大概降了三成。4. 完整实操从零搭建这套工作流4.1 环境准备与目录结构先把目录建好。用户级命令目录是~/.claude/commands/如果不存在就手动创建。项目级的是项目根/.claude/commands/。我的建议是两层都用通用的 10 个命令放用户级项目特有的补充命令放项目级。mkdir -p ~/.claude/commands mkdir -p .claude/commands目录建好后把 10 个命令文件逐个放进去。文件名就是命令名比如审查.md、提交.md。这里有个细节文件名不要带空格中文没问题但空格会导致调用时解析异常。4.2 逐个命令的落地配置我挑几个最有代表性的命令把完整配置和设计意图讲透。/提交命令文件~/.claude/commands/提交.md根据当前 git 暂存区的改动生成一条规范的中文提交信息。 要求 - 格式类型(范围): 简述 - 类型从 feat/fix/refactor/docs/test/chore 中选 - 简述不超过 50 字用祈使句 - 如果改动较大在正文补充变更点每点一行 先执行 git diff --staged 查看改动再生成信息。 只输出提交信息本身不要额外解释。这个命令的价值在于统一团队提交规范。以前每个人提交信息风格各异现在敲一下/提交出来的格式完全一致。注意它明确要求先看 diff这是为了避免 AI 凭空编造提交内容。/排查命令文件~/.claude/commands/排查.md根据报错信息定位问题根因。 报错信息$ARGUMENTS 排查步骤 1. 解析报错判断是语法、运行时还是逻辑错误 2. 定位到最可能的代码位置 3. 给出根因分析不要只描述现象 4. 提供修复方案并说明为什么这样修 5. 指出是否有同类隐患 如果信息不足以定位列出需要我补充的信息。这个命令我用了最多。它的设计重点是要求根因而非现象。很多 AI 助手看到报错就给你贴个修复代码但不说为什么。这个命令强制它走完解析—定位—根因—修复—隐患五步排查质量高很多。/计划命令文件~/.claude/commands/计划.md把需求拆解成可执行的任务清单。 需求$ARGUMENTS 输出要求 - 按依赖顺序排列任务 - 每个任务标注预估工作量和风险点 - 标出可以并行的任务 - 最后给出验收标准 如果需求描述不清先向我提问不要臆测。这个命令适合新功能开发前用。它把模糊需求变成结构化清单尤其是标出可并行任务和验收标准这两点是普通任务拆解容易漏的。4.3 参数计算与调用示例有人问过命令里的参数到底怎么传才不出错。我的经验是路径用相对路径从项目根算起多参数用空格分隔复杂要求放最后。举个实际例子。假设我要重构一个函数调用方式是/重构 src/services/order.ts 把同步循环改成 Promise.all 并发这里$ARGUMENTS收到的是src/services/order.ts 把同步循环改成 Promise.all 并发。提示词里我会写第一个空格前是文件路径其余是重构要求这样 AI 就能正确拆分。再比如/测试命令我想给某个函数补测试可以这样调/测试 src/utils/format.ts 重点覆盖空输入和超长字符串参数拆解逻辑同上。实测下来只要提示词里把拆分规则写清楚AI 拆参数基本不会错。4.4 验证工作流是否生效配置完别急着用先验证。敲/看命令列表里有没有出现这 10 个中文命令。如果没出现八成是文件编码或路径问题。检查两点文件是不是 UTF-8 编码目录是不是在正确位置。验证通过后拿一个真实的小任务试跑。我建议先用/解释试因为它输入输出最简单容易判断是否正常工作。跑通了再试复杂的/重构、/排查。5. 常见问题与排查技巧实录5.1 命令不生效的排查表这套工作流搭起来最容易卡在命令不生效。我把遇到过的问题整理成表按出现频率排序。现象可能原因解决方法命令列表里没有中文命令文件编码非 UTF-8用编辑器另存为 UTF-8命令出现但调用无反应提示词为空或只有描述检查文件正文是否有内容参数没传进去占位符写错确认是$ARGUMENTS不是$ARGUMENT中文命令名乱码终端编码问题切换终端编码为 UTF-8项目级命令不生效目录层级不对确认在项目根目录下这张表基本覆盖了九成的问题。其中编码问题最常见尤其是从 Windows 复制文件到 macOS 的时候很容易带上 GBK 编码。5.2 输出质量不稳定的应对前面提过输出会波动除了那三个技巧还有个进阶办法给命令加示例输出。在提示词里贴一段你期望的输出样例AI 会模仿这个风格。这招对格式要求高的命令特别管用比如/日志和/文档。另一个办法是分阶段调用。复杂任务不要指望一个命令搞定拆成两步。比如先/计划拆任务再对每个任务单独/重构。这样每步的上下文都聚焦质量更稳。提示如果某个命令连续几次输出都不理想别急着改提示词先看看是不是任务本身太模糊。很多时候问题不在命令在输入。5.3 跨工具迁移的注意事项这套命令本质是 Markdown 提示词所以理论上可以迁移到任何支持自定义命令的 CLI 工具。但迁移时有几个坑要注意。不同工具的参数占位符语法不一样。Claude Code 用$ARGUMENTS别的工具可能用{{args}}或$1。迁移时这部分必须改。另外命令的存放目录和加载机制也各不相同得查对应工具的文档。我的建议是把提示词内容和工具配置分离。提示词正文单独维护一份迁移时只改占位符和目录内容不动。这样一套提示词可以喂给多个工具不用重复维护。5.4 我踩过的三个坑第一个坑是命令名太长。我一开始把命令命名成/生成单元测试结果每次敲都要打五个字反而累。后来改成/测试两个字搞定。命令名要短描述可以长。第二个坑是提示词里塞太多要求。有个命令我写了十几条检查项结果 AI 顾此失彼每条都做得不深。后来砍到五条核心的质量反而上去了。提示词不是越多越好聚焦才有效。第三个坑是忘了版本控制。命令文件改来改去有次改坏了想回退发现没提交。现在我把~/.claude/commands/也纳入了 git 管理改坏了随时回滚。这个习惯强烈建议养成。6. 这套工作流的扩展方向10 个命令只是起点。用顺了之后你会发现很多操作都可以固化成命令。我最近在加的是/评审专门做 PR 级别的整体评审比/审查更宏观。还有/迁移用于把代码从一种框架迁到另一种。扩展的时候有个原则先手动做几次确认流程稳定了再固化成命令。不要一上来就为想象中的需求写命令那样很容易写出用不上的东西。命令是给高频操作用的低频的一次性任务直接对话就行。另外命令之间可以组合。比如/计划拆完任务后对每个任务调/重构或/测试形成一条流水线。我现在的习惯是新功能先/计划开发中随时/解释和/排查提交前/审查加/提交发版前/日志。这套组合拳打下来整个开发流程的 AI 参与度很高但每一步都可控。最后分享一个小技巧给命令加个使用统计。在提示词末尾让它输出一行标记比如[命令:审查]这样你回头 grep 日志就知道哪个命令用得最多、哪个几乎没用。用得少的命令要么删掉要么说明设计有问题值得复盘。我自己统计下来/排查和/提交是绝对主力/文档用得最少后来我把它合并进了/解释命令数从 10 个精简到 9 个反而更清爽。工具是给自己用的够用就好不必追求数量。