1. 为什么我要把中文命令塞进 Claude Code用 Claude Code 写代码的人大概都经历过同一个尴尬英文指令敲得飞起一到中文场景就卡壳。比如你想让它把这段日志里的报错按时间线整理成表格用英文写要绕一大圈用中文写它又经常理解偏。更麻烦的是Claude Code 原生的斜杠命令全是英文的/compact、/model、/resume这些记起来不难但每次都要在脑子里做一次中文需求 → 英文命令的翻译时间一长就烦。我自己的痛点在三个地方。第一是重复性指令。每天开工前我都要做同一套动作让它读一遍项目结构、检查 git 状态、列出待办、确认当前分支。这些动作如果每次手敲一天下来光打字就浪费十几分钟。第二是中文语义的丢失。Claude Code 对中文的理解其实不差但如果你用英文命令去触发中文任务中间那层转换经常丢细节比如帮我看看这个函数有没有边界问题翻译成英文就变成了review this function颗粒度完全不一样。第三是团队协作。我带的几个新人英文命令记不全每次都要翻文档效率极低。如果能有一套中文命令他们上手成本直接砍半。所以我就动了念头能不能把常用的中文指令封装成 Claude Code 的自定义命令让它像原生斜杠命令一样工作答案是能而且比想象中简单。Claude Code 支持在项目目录下放.claude/commands/文件夹里面每个 Markdown 文件就是一个自定义命令文件名就是命令名文件内容就是提示词模板。你敲/你的命令名它就把文件内容作为提示词发给模型。这个机制原本是给英文用户设计的但中文完全能用甚至因为中文表达更紧凑效果反而更好。我最终装了 10 个命令覆盖了日常开发里最高频的场景项目体检、代码审查、日志分析、提交信息生成、测试补全、依赖检查、文档生成、重构建议、性能排查、以及一个万能翻译命令把中文需求转成精准的英文提示词。这 10 个命令装完之后我的工作流从想需求 → 翻译成英文 → 敲命令 → 等结果变成了想需求 → 敲中文命令 → 等结果中间那层翻译彻底消失了。这篇文章我会把这 10 个命令的完整实现、每个命令背后的设计逻辑、以及我在实测中踩过的坑全部摊开讲。不管你是刚装好 Claude Code 的新手还是已经用了一段时间但觉得效率上不去的老手这套东西都能直接抄作业。我会尽量把为什么这么设计讲清楚因为命令本身很简单难的是知道什么时候该用哪个、提示词该怎么写才能让模型稳定输出。2. 自定义命令的加载机制与目录约定2.1 命令文件放在哪、怎么被识别Claude Code 的自定义命令走的是文件系统约定不是配置文件。你不需要改任何 JSON 或 YAML只需要在项目根目录下建一个.claude/commands/文件夹然后把 Markdown 文件丢进去。文件名去掉.md后缀就是命令名。比如你建一个check.md那命令就是/check。如果你建的是review-code.md命令就是/review-code。这个命名规则很直白但有几个细节容易踩坑。第一命令名不支持中文文件名。我一开始想偷懒直接把文件命名成项目体检.md结果 Claude Code 识别不了敲/项目体检没反应。后来改成health.md命令名用英文但文件内容全中文这样就正常了。所以命令名保持英文或者拼音提示词内容用中文这是最稳的组合。第二目录层级决定命令的作用范围。放在项目根目录的.claude/commands/里这个命令只在这个项目里可用。如果你放在用户主目录的~/.claude/commands/里那就是全局命令所有项目都能用。我的做法是通用型命令比如翻译、日志分析放全局项目专属命令比如这个项目的部署检查放项目里。这样既不会污染全局又不会每个项目重复建。第三子目录会变成命令的命名空间。如果你在.claude/commands/下建一个git/子目录里面放commit.md那命令就是/git:commit。这个机制很适合做命令分组比如把所有和测试相关的命令放test/目录下敲的时候有自动补全提示不容易记混。2.2 提示词模板里的变量与上下文注入命令文件的内容不是死板的文本它支持变量替换和上下文注入。最常用的几个变量是$ARGUMENTS、$1、$2这种位置参数。比如你写一个explain.md内容是请解释以下代码$ARGUMENTS那你敲/explain src/utils/date.ts的时候$ARGUMENTS就会被替换成src/utils/date.ts。这个机制让命令从固定提示词变成了带参数的函数实用性直接翻倍。除了参数Claude Code 还会自动注入一些上下文。比如当前工作目录、git 状态、最近打开的文件列表这些信息在命令执行时是可用的。你可以在提示词里写基于当前项目的 git 状态模型就能拿到真实数据。我实测下来这个上下文注入是自动的不需要你手动声明但你要在提示词里明确让模型去用这些上下文否则它可能忽略。还有一个隐藏技巧命令文件里可以引用其他文件。比如你写请参考 .claude/rules/coding-style.md 的规范来审查代码模型会去读那个文件的内容。这个引用语法在 Claude Code 里是通用的命令模板里也能用。我用这个机制把团队的代码规范、API 约定、命名规则都抽成了独立文件命令里只写引用改规范的时候只改一个地方所有命令自动生效。2.3 命令的触发方式与执行边界自定义命令的触发方式和原生命令一样在对话输入框里敲/就会弹出补全列表。但有个区别原生命令是 Claude Code 内置的逻辑自定义命令本质上是把一段提示词发给模型。这意味着自定义命令的执行结果完全取决于模型的理解不像原生命令那样有确定性的行为。这个区别很重要它决定了你写命令时的思路——你不是在写脚本你是在写提示词。执行边界方面自定义命令默认只能读不能写。也就是说模型可以读文件、分析代码、给出建议但不会直接修改你的文件。如果你想让它写文件需要在提示词里明确要求而且 Claude Code 会弹出确认。我建议大部分命令保持只读属性输出建议让用户自己决定要不要采纳。只有像生成提交信息这种明确要产出内容的命令才让它写。另外命令执行时模型能看到整个项目的文件树但不会自动读所有文件内容。它按需读取所以你不用担心上下文爆炸。但如果你的命令要求它审查整个项目它可能会读很多文件这时候要注意 token 消耗。我的经验是命令里尽量指定范围比如审查 src/ 下最近修改的 5 个文件而不是审查整个项目。3. 十个中文命令的完整实现与设计思路3.1 项目体检命令 /health这个命令是我每天开工第一个敲的。它的作用是快速摸清项目当前状态目录结构、依赖版本、git 分支、未提交改动、以及有没有明显的配置问题。提示词我改了七八版才稳定下来核心难点是让模型输出结构化结果而不是一堆废话。最终版本的提示词是这样的请对当前项目做一次快速体检输出以下信息 1. 项目类型与技术栈根据 package.json / pyproject.toml / go.mod 等判断 2. 当前 git 分支与最近 3 条提交 3. 未提交的改动文件列表git status 4. 依赖数量与是否有明显过时版本 5. 项目根目录下的关键配置文件清单 6. 任何你注意到的异常比如缺少 .gitignore、依赖冲突、配置文件格式错误 输出用 Markdown 表格不要展开解释每项一行。这个命令的关键设计在于不要展开解释。我一开始没加这句模型每次都要写一大段分析看着累。加上之后输出变成了一张紧凑的表格扫一眼就知道项目状态。另外任何你注意到的异常这一条很有价值它经常能发现我忽略的问题比如某次它提示我.env文件被提交到了 git我一看还真是赶紧加了.gitignore。实测下来这个命令在 10 秒内能跑完输出大概 20 行表格。我把它设成了每天第一个动作比手动敲git status、ls、cat package.json快得多而且信息更全。3.2 代码审查命令 /review代码审查是我用得第二多的命令。它的设计目标是给定一个文件或一段 diff输出按严重程度排序的问题列表每条问题附带具体行号和修复建议。这里最大的坑是模型太客气它经常把明显的问题说成可以考虑优化导致你分不清哪些必须改、哪些可选。我的解法是在提示词里强制分级请审查 $ARGUMENTS 的代码按以下三级分类输出问题 - P0必须修复会导致 bug、安全问题、数据丢失的 - P1建议修复影响可维护性、性能、可读性的 - P2可选优化风格、命名、注释类的 每条问题格式行号 | 级别 | 问题描述 | 修复建议 不要输出整体看起来不错这类客套话直接列问题。 如果某一级没有问题写无。这个分级机制效果立竿见影。P0 的问题模型会非常认真地找因为它知道这是必须修复级别。我实测过一个有并发问题的函数模型准确标出了 P0并给出了加锁的具体位置。P1 和 P2 则帮我处理了很多命名和结构问题。还有一个细节$ARGUMENTS可以传文件路径也可以传git diff的输出。我经常在提交前敲/review git diff HEAD让它审查我这次改动的所有内容。这比逐文件审查更聚焦因为它只看你改了什么不会翻出一堆历史遗留问题。3.3 日志分析命令 /logs这个命令解决的是一堆报错日志里找根因的问题。原始日志通常几百上千行人工看要很久。我设计的提示词是让它做三件事按时间线整理、按错误类型聚类、给出最可能的根因。请分析以下日志内容输出 1. 时间线摘要按时间顺序列出关键事件忽略重复的常规日志 2. 错误聚类把所有 ERROR / WARN 按类型分组每组给出出现次数 3. 根因推测基于错误出现的顺序和频率推测最可能的根本原因 4. 建议排查方向给出 2-3 个具体的下一步动作 日志内容 $ARGUMENTS这个命令的难点在于日志量。如果日志太长模型会截断。我的做法是先用tail -n 500或grep ERROR预处理再把结果传给命令。另外忽略重复的常规日志这句很重要否则模型会把大量 INFO 日志也列出来稀释了关键信息。实测中这个命令帮我定位过一个内存泄漏问题。日志里有一堆GC overhead limit exceeded模型聚类后发现它们都出现在某个定时任务执行之后推测是那个任务里有对象没释放。我顺着查下去果然是一个缓存 Map 只增不减。这种从日志模式反推代码问题的能力是纯人工看日志很难快速做到的。3.4 提交信息生成命令 /commit写 commit message 是很多人的痛点尤其是团队有规范的时候。这个命令的思路是读当前 git diff按 Conventional Commits 规范生成提交信息同时给出一个更详细的中文说明。请基于当前 git diff 生成提交信息要求 1. 第一行type(scope): 简短描述type 从 feat/fix/refactor/docs/test/chore 中选 2. 空一行 3. 正文用中文列出这次改动的主要内容每条一行以 - 开头 4. 如果改动涉及多个不相关的模块建议拆分成多个提交 不要输出任何解释直接给提交信息。这里的关键是不要输出任何解释。我一开始没加模型每次都要先分析一遍 diff 再给提交信息多花好几秒。加上之后直接出结果我复制粘贴就能用。还有一个进阶用法把团队规范文件用引用进来。比如.claude/rules/commit-convention.md这样生成的提交信息会自动符合团队规范不用每次在提示词里重复。我们团队的规范里规定了 scope 的取值列表引用之后模型就不会乱写 scope 了。3.5 测试补全命令 /test这个命令是给已有函数补单元测试的。设计目标是读指定文件找出没有测试覆盖的函数生成测试用例。难点在于判断哪些函数需要测试——不是所有函数都值得测比如纯 getter/setter 就没必要。请为 $ARGUMENTS 中的函数补全单元测试要求 1. 先列出文件中所有导出函数标注哪些已有测试、哪些没有 2. 对没有测试的函数按重要性排序核心逻辑优先工具函数其次 3. 为前 3 个最重要的函数生成测试用例 4. 测试用例要覆盖正常路径、边界条件、错误处理 5. 使用项目现有的测试框架根据 package.json 判断 输出格式先给测试文件路径建议再给完整测试代码。这个命令我用了大概两个月最大的收获是它帮我发现了几个看起来简单但边界很多的函数。比如一个日期格式化函数模型生成的测试覆盖了闰年、时区、空值、非法格式四种情况其中时区那条我自己都没想到。当然模型生成的测试不能直接信我每次都会跑一遍有几次它写的断言是错的需要手动修。3.6 依赖检查命令 /deps这个命令检查项目依赖的健康状况有没有已知问题版本、有没有重复依赖、有没有可以升级的。它不联网纯粹基于本地package.json和lock文件分析。请检查当前项目的依赖状况输出 1. 直接依赖数量与间接依赖数量 2. 是否有同一包的多版本共存从 lock 文件判断 3. 是否有明显过时的依赖主版本落后 2 个以上 4. 是否有依赖体积异常大根据 node_modules 大小 5. 建议升级的依赖列表按优先级排序 用表格输出不要展开解释。这个命令的价值在于多版本共存检测。npm 生态里同一个包被不同依赖引用不同版本是常事但有时候会导致奇怪的 bug。模型能从 lock 文件里把这种情况揪出来比手动翻 lock 文件快得多。另外体积异常大这条也很实用我靠它发现过一个测试依赖意外进了生产依赖导致打包体积翻倍。3.7 文档生成命令 /doc给代码补文档是件枯燥的事但又是团队协作必需的。这个命令读指定文件生成 JSDoc 或 docstring 风格的注释直接可以贴回代码里。请为 $ARGUMENTS 中的导出函数生成文档注释要求 1. 使用项目现有的注释风格JSDoc / docstring / 其他 2. 每个函数包含功能描述、参数说明类型含义、返回值说明、可能的异常 3. 描述用中文类型用英文 4. 只输出注释块不要输出函数体 5. 如果函数逻辑复杂补充一个简短的使用示例 按函数在文件中的顺序输出。这个命令的坑在于只输出注释块。如果不加这句模型会把整个函数重写一遍输出巨长。加上之后输出干净很多我直接复制注释贴到函数上方就行。另外使用示例这条对复杂函数特别有用模型经常能写出我没想到的调用方式。3.8 重构建议命令 /refactor这个命令和/review的区别是/review找问题/refactor给重构方案。它会分析代码结构指出可以抽象、可以拆分、可以简化的地方并给出具体的重构步骤。请分析 $ARGUMENTS 的重构空间输出 1. 当前代码的主要问题重复代码、过长函数、职责不清等 2. 每个问题的具体位置行号范围 3. 重构方案具体怎么改改成什么样 4. 重构风险改动会影响哪些调用方 5. 建议的重构顺序先改哪个后改哪个 不要直接改代码只给方案。不要直接改代码这句是必须的。重构是高风险操作让模型直接改容易出问题。我只要方案自己判断要不要采纳。实测中这个命令最常发现的问题是过长函数和重复逻辑它给出的拆分建议通常很合理但偶尔会过度设计把一个简单函数拆成三个。所以我的原则是采纳它指出的问题但重构方案自己再过滤一遍。3.9 性能排查命令 /perf这个命令针对性能问题分析代码里可能的性能瓶颈循环里的重复计算、不必要的内存分配、同步阻塞操作等。请分析 $ARGUMENTS 的性能问题输出 1. 时间复杂度分析每个函数的大 O 复杂度 2. 性能瓶颈具体哪一行、为什么慢 3. 优化方案怎么改能提升性能 4. 优化收益预估大概能提升多少 5. 是否有过度优化风险改动是否值得 按瓶颈严重程度排序。过度优化风险这条是我特意加的。模型有时候会建议一些微优化比如把for循环改成while收益微乎其微但降低了可读性。加上这条之后它会主动标注这个优化收益很小不建议改帮我省了不少纠结。3.10 万能翻译命令 /zh这个命令严格来说不是开发命令而是中文需求转英文提示词。有时候我需要用英文和模型交流比如查英文文档但脑子里想的是中文。这个命令把中文需求翻译成精准的英文提示词保留所有技术细节。请把以下中文需求翻译成英文提示词要求 1. 保留所有技术术语的准确性 2. 补充中文里省略但英文需要明确的上下文 3. 输出格式先给英文提示词再给一行中文回译用于确认 4. 如果中文需求有歧义列出 2 种可能的英文表达 中文需求 $ARGUMENTS这个命令的中文回译设计很关键。它让我能快速确认翻译有没有跑偏。有几次我发现回译和我的原意不符一看是某个术语翻译错了及时纠正。另外列出 2 种可能表达对歧义需求很有用我可以选更贴切的那个。4. 实测中踩过的坑与稳定性调优4.1 命令不生效的三种常见原因装完命令敲了没反应这是新手最容易遇到的问题。我总结下来有三种原因。第一种是目录位置错了。.claude/commands/必须在项目根目录不能在src/或其他子目录里。判断方法很简单在项目根目录敲ls -la .claude/commands/能看到你的 md 文件就对了。第二种是文件名有特殊字符。中文、空格、大写字母都可能导致识别失败。我的建议是全部用小写英文加连字符比如review-code.md最稳。第三种是Claude Code 没重启。自定义命令是在启动时扫描的你新建了命令文件但没重启它不会加载。改完命令文件后退出重进一次就好。还有一个隐蔽的坑命令名和原生命令冲突。比如你建一个model.md命令是/model但/model是 Claude Code 原生的切换模型命令你的自定义命令会被原生命令覆盖永远触发不了。所以建命令前先敲/看看补全列表里有没有重名。4.2 提示词写得太客气导致输出注水这是我踩过最大的坑。一开始我写提示词很礼貌什么请帮我仔细分析一下、如果可以的话结果模型输出全是客套话和分析过程真正有用的结论藏在最后。后来我把所有提示词都改成了命令式直接说输出以下内容、不要解释、直接给结果。效果立竿见影输出长度砍了一半信息密度翻倍。具体来说有几个句式特别管用。第一是不要输出任何解释放在提示词末尾能砍掉大量废话。第二是用表格输出强制结构化模型没法注水。第三是如果某项没有问题写无防止模型为了凑内容硬编。第四是按严重程度排序让模型做优先级判断而不是平铺直叙。还有一个反直觉的经验提示词越短越稳定。我一开始写的提示词有几百字各种要求堆在一起结果模型经常顾此失彼。后来精简到 100 字以内只保留最核心的 3-4 条要求输出反而更稳定。原因是模型在长提示词里容易迷失重点短提示词让它聚焦。4.3 上下文超长时的截断策略Claude Code 有上下文窗口限制虽然具体数字会变但肯定不是无限的。当你用/logs分析一个几千行的日志或者用/review审查一个大文件时很容易触发截断。截断的表现是模型只分析了前半部分后半部分完全没提。我的应对策略是预处理 分段。对于日志先用grep或tail缩小范围只把关键部分传给命令。对于大文件审查先按函数拆分逐个审查。对于git diff如果改动超过 500 行我会分几次提交每次审查一部分。还有一个技巧是在提示词里明确告诉模型如果内容被截断请指出。加上这句之后模型会在输出末尾标注注意输入内容可能不完整这样我就知道要重新处理。虽然不能解决截断本身但至少不会让我误以为分析完整了。4.4 让命令输出可复现的确定性技巧自定义命令最大的问题是不确定性——同样的输入两次运行结果可能不一样。这在需要精确输出的场景比如生成提交信息很麻烦。我摸索出几个提升确定性的技巧。第一是固定输出格式。在提示词里给出精确的模板比如每条问题格式行号 | 级别 | 描述 | 建议模型会严格按模板输出不会自由发挥。第二是给出示例。对于复杂输出我在提示词里放一个示例模型会模仿示例的格式。第三是降低温度。虽然 Claude Code 不直接暴露温度参数但你可以通过请给出最确定的答案不要发散这类指令间接影响。第四是分步执行。把复杂任务拆成多个命令每个命令只做一件事比一个命令做所有事更稳定。实测下来加了这些约束之后同一个命令的输出一致性从大概 60% 提升到了 85% 以上。剩下的 15% 波动主要来自模型对边界情况的理解差异这个很难完全消除但可以通过人工复核兜底。5. 把命令串成工作流的组合玩法5.1 日常开发的命令链单个命令好用但真正的效率提升来自把命令串成链。我日常开发有一套固定的命令链从开工到提交全程不用离开 Claude Code。开工第一步是/health摸清项目状态。如果发现有未提交改动先/review git diff HEAD审查一遍。确认没问题后如果是新功能开发我会用/refactor看看当前代码有没有需要先清理的地方。写代码过程中遇到不确定的函数就/test补测试遇到性能疑虑就/perf分析。写完一个阶段用/doc补文档最后/commit生成提交信息。这套链条跑下来我发现自己手动敲 git 命令的次数少了很多而且每个环节都有模型把关漏掉问题的概率明显降低。尤其是/review和/test的组合一个找问题一个补覆盖配合起来能挡住大部分低级错误。5.2 用命令做代码交接团队协作里代码交接是个麻烦事。新人接手一个模块要花很久才能理清结构。我用命令组合做了一个交接包先/health给出项目概览再/doc给核心文件补文档然后/refactor指出需要重点关注的结构问题最后/deps说明依赖状况。这四份输出拼起来就是一份完整的交接文档。实测中这套交接包帮新人把上手时间从两三天缩短到了半天。新人反馈说最有价值的是/refactor的输出因为它直接指出了哪些地方容易改出 bug这是看代码本身很难快速判断的。当然交接包不能替代实际读代码但能提供一个很好的地图。5.3 命令的迭代与版本管理命令不是写完就固定的随着项目演进提示词也要调整。我的做法是把.claude/commands/目录纳入 git 管理每次改命令都提交这样能看到命令的演进历史。另外我会在命令文件顶部加一行注释记录这个命令的版本和最后修改原因比如!-- v3: 增加 P0/P1/P2 分级2024-xx-xx --。这样回头看的时候知道为什么这么改。还有一个经验是定期清理。我一开始装了 20 多个命令后来发现常用的就那 10 个剩下的要么重复要么用不上。清理之后补全列表更清爽找命令更快。我的标准是如果一个命令一个月没用过就删掉或者合并到其他命令里。命令不在多在于每个都真正解决问题。6. 关于这套工作流我个人的几点体会装完这 10 个命令用了大概两周时间但真正让我觉得值了的是第三周。那天我处理一个线上问题从看日志到定位根因到修复提交全程只用了 40 分钟。换作以前光是在日志里翻找和写提交信息就要花掉一半时间。这套命令没有让我变聪明但它把我从重复劳动里解放出来了让我能把精力放在真正需要判断的地方。如果你也想搭一套我的建议是从 3 个命令开始/health、/review、/commit。这三个覆盖了最高频的场景装完立刻能感受到效率提升。用顺了之后再逐步加/logs、/test、/refactor。不要一上来就装 10 个那样你记不住反而增加负担。最后一个小心得命令的提示词要当成代码来维护。每次输出不满意不要凑合回去改提示词。改个三五版很正常改到稳定为止。我现在的 10 个命令每个都至少迭代过 5 版最常用的/review改了 12 版。这个过程本身就是对怎么和模型有效沟通的训练练出来的能力不只用在 Claude Code 上用在任何 AI 工具上都管用。