说实话Claude Code 用久了最让我上瘾的不是它聊天多聪明而是那套斜杠命令机制。我花了两三个星期往.claude/commands目录里陆续塞了 10 个中文命令把读代码、审代码、改 Bug、写测试、补文档这些高频动作全部固化成了标准流程。这套 AI 编程工作流包现在每天跟着我跑项目帮我省下了大量重复敲提示词的时间也让团队新同学上手项目时不再两眼一抹黑。这篇文章就把这 10 个命令的完整内容、设计思路、安装配置流程和实际踩过的坑一次讲清楚。适合已经在用 Claude Code、或者正准备入坑、想把命令行 AI 从“随问随答”升级成“标准化流水线”的开发者参考。1. 为什么要给 Claude Code 造一套中文命令1.1 斜杠命令Claude Code 里最被低估的功能很多人把 Claude Code 当成一个挂在终端里的聊天窗口想到什么问什么。这种用法没问题但效率其实只发挥了三成。Claude Code 真正的杀手锏是它支持用户自定义斜杠命令Slash Command你在终端里敲/就能呼出一个命令列表选中之后Claude 会按照命令文件里预写好的提示词去执行任务。这套机制的本质是把“每次都要重复输入一大段提示词”变成“敲两个字符就搞定”。比如你想让我审查代码不需要再打一遍“请你以资深工程师视角检查这个文件的安全性、性能、可维护性”只需要输入/审代码 src/auth.ts剩下的事情命令文件替你安排。命令文件就是普通的 Markdown 文件放在.claude/commands目录下文件名就是命令名内容最前面是 YAML 格式的前置信息后面是命令正文正文里可以用$ARGUMENTS、$1、$2这些占位符接收用户输入。Claude 在收到/命令名 参数时会把命令文件整体加载进上下文再把参数替换进去最后按照正文里的指示执行。整个过程涉及读文件、写文件、跑命令时Claude 会自主调用自己的工具不需要你手把手指挥。我觉得这个功能被严重低估了。提示词写得好Claude Code 的输出质量和稳定性会提升一大截把提示词固化成命令就等于把“某类任务的最佳做法”沉淀到了工作流里团队里的人都能复用不用每个人各自发挥。1.2 中文命令解决了谁的痛点我认识不少开发者英文读写没问题但和人交流、写需求文档、看内部资料时脑子里第一反应还是中文。这种情况下如果你用的命令和提示词全是英文每次触发前都要先在脑子里“翻译”一遍命令一多反而成了负担。中文命令最直接的好处是降低认知成本。命令名用中文看到/读代码、/修Bug你不需要回忆这个命令是干嘛的光看名字就知道用途。命令输出也用中文评审意见、Bug 诊断、接口文档这些交付物可以直接贴进中文团队的需求单和缺陷管理系统不用二次转换。这个设计对团队协作尤其有价值。我现在的工作流里新同学接手一个陌生仓库第一件事就是敲/读代码让 Claude 把入口、数据流、核心模块讲一遍Code Review 之前统一走/审查代码保证每个人的审查标准一致。命令文件放在项目仓库里随 git 走新人 clone 下来就自动有了全套命令这才是把“个人技巧”变成“团队资产”的正确姿势。1.3 这套命令包的设计原则在动手写命令之前我先给自己定了几条规矩这几条直接决定了命令包好不好用。第一一个命令只干一件完整的事。审查代码就是审查代码不要顺便把修 Bug 也干了生成接口文档就只生成文档不要顺手改代码。混在一起会让输出变得不可控也不方便事后校验。第二改代码类命令默认“先诊断、后动手”。比如/修Bug我要求它先输出根因分析报告确认了再改/重构必须保持行为不变。AI 改代码最怕的就是“自信地改错”强制加一道确认环节能避免大量事故。第三输出格式标准化。凡是会产出报告的都要求用表格、分级列表、固定章节。这样我扫一眼就能定位重点不用在一大段散文里找结论。第四控制上下文消耗。命令正文里我会明确限制“如果代码量超过多少行先讲骨架”防止 Claude 一口气读太多文件把上下文预算烧光导致后半程回答质量断崖式下降。这几条原则看着简单但真写命令时特别容易违反尤其是“顺手多做一步”。我前几版命令里就混入过“顺便优化一下”后来全改掉了。2. 10 个中文命令逐个拆解2.1 先看命令文件长什么样命令文件是 Markdown 格式开头用两行---包起来的是 YAML 前置信息至少要有description建议加上argument-hint需要限制工具时加allowed-tools。后面是正文正文里可以放$ARGUMENTS、$1、$2等占位符接收用户敲的参数。拿我最常用的/修Bug举例完整命令文件长这样--- description: 定位并修复指定 Bug先给诊断报告再改代码 argument-hint: [Bug 现象描述或相关文件路径] --- 你是经验丰富的调试工程师。针对 $ARGUMENTS 1. 先复现问题判断是输入数据、边界条件还是并发时序导致 2. 给出一份诊断报告根因、影响范围、触发条件、证据链 3. 提出修复方案默认选最小改动方案说明为什么不动其他代码 4. 修复后列出需要补充的回归测试用例 在没有确认根因之前绝对不要乱改代码。如果信息不足以定位直接列出需要补充的信息和日志。这里有两个细节值得注意。$ARGUMENTS会替换成用户在/修Bug后面输入的全部内容可以是描述也可以是文件路径。正文最后那句“绝对不要乱改代码”不是废话Claude 这类模型在任务压力下很容易“表现欲上头”直接给出一个大改方案必须有书面约束。文件保存为.claude/commands/修Bug.md在 Claude Code 里敲/修Bug命令就出来了。项目级命令、用户级命令、企业级命令的位置有区别这个我在第三章细讲。2.2 读代码类读懂别人项目的三个命令第一组命令解决的是“读”的问题/读代码、/审查代码、/解释报错。/读代码的核心是让 Claude 当导师。我看过太多介绍代码的提示词要求“详细讲解”结果 Claude 把每个函数都念一遍读完等于没读。所以我故意加了约束超过 500 行先讲骨架而且必须讲清楚数据流和副作用。命令正文是这样--- description: 解释指定目录/文件的核心逻辑生成阅读导图 argument-hint: [目标路径] --- 请扮演一位耐心的导师用通俗易懂的方式讲解 $ARGUMENTS 1. 先说明整体架构入口在哪数据流怎么走外部依赖有哪些 2. 按调用链拆解核心函数讲清楚输入、输出、副作用 3. 标记最值得注意的坑隐藏全局状态、隐式转换、时序依赖 4. 最后用文本流程图描述主线流程 如果代码量大于 500 行优先讲解骨架和关键路径不要逐行啰嗦。/审查代码走的是另一个方向它产出的是问题清单不是讲解--- description: 审查代码质量、安全隐患和坏味道输出分级问题清单 argument-hint: [文件或目录路径] --- 你是一名严谨的资深代码审查员。请审查 $ARGUMENTS重点检查 1. 逻辑错误与边界条件遗漏 2. 安全隐患注入、越权、敏感信息泄露 3. 性能隐患N1 查询、无谓循环、内存泄漏 4. 可维护性问题命名、重复代码、注释与实现不符 输出格式按“严重/建议/可选”三级分组每条给出文件位置、原因说明和修改建议最后用代码块给出关键修改示例。先报告不要直接改写全部文件。/解释报错是救急用的。遇到一串陌生报错与其复制去搜索引擎不如直接粘给这个命令--- description: 翻译并定位错误日志/异常堆栈 argument-hint: [粘贴报错信息] --- 请解读以下报错信息$ARGUMENTS 1. 用一句话说清楚错误本质不要只翻译原文 2. 列出最常见的 3 个触发原因按概率排序 3. 结合报错堆栈定位本项目可能的出错位置必要时搜索代码 4. 给出排查命令建议复现请求、调整日志级别、补单测用例这三个命令设计时有个共同点都强制要求输出结构化结果要么是“骨架关键路径”要么是“分级清单”要么是“一句话本质概率排序”。因为读代码的场景里我真正需要的是快速形成心智模型而不是一篇优美的代码赏析。2.3 改代码类修 Bug、重构、做性能分析第二组命令解决“改”的问题也是最容易翻车的部分。/修Bug我在 2.1 已经展示过这里重点说它和最怕发生的事——AI 猜一个原因就直接改。所以我特意要求“先诊断后修复”并且提示词里写了“没有确认根因之前绝对不要乱改代码”。/重构的命令文件把“行为不变”当成铁律--- description: 对指定模块进行小步重构保持行为不变 argument-hint: [目标文件路径] --- 请对 $ARGUMENTS 进行行为不变的重构 1. 先量化描述当前问题圈复杂度、重复代码比例、函数长度、耦合点 2. 给出重构计划按小步执行每步必须可独立测试 3. 优先消除重复代码、过长函数、深层嵌套、全局可变状态 4. 完成后列出行为等价性的验证方法现有测试/临时对比脚本 严禁在重构过程中顺手修改业务逻辑如果你觉得某个改动会改变行为停下来单独说明。这里藏着一条经验“小步执行每步可独立测试”听起来像流水账但对大模型特别重要。一次丢给它一个 800 行的老模块让它重构它大概率会给你一个“全新的、看起来更好但行为变了”的版本逼它分步走每一步都能验证风险就小很多。/性能分析则强调用数据说话--- description: 从代码层面分析性能瓶颈并给出优化建议 argument-hint: [目标文件或接口路径] --- 以性能工程师视角分析 $ARGUMENTS 1. 先建立基线这段代码的时间复杂度、空间复杂度热点在哪 2. 检查常见性能陷阱循环内 IO、重复计算、不必要拷贝、锁竞争、缓存失效 3. 按“收益/成本比”排序优化建议先写收益大改动小的 4. 每条建议写明预期提升量级常数倍/线性/数量级不要给没有数据的空泛思路 如果无法从静态代码判断指明需要补充的 profiling 数据。我吃过不少亏让 AI 优化性能它把for循环改成map然后说“性能提升”实际上根本没变化。所以这个命令必须要求“预期提升量级”写不出来就说明它没有把握我会直接跳过。2.4 交付物类写测试、提交信息、接口文档、搭骨架剩下四个命令负责“输出交付物”它们共同的特点是产出物直接可用不需要大改。/写测试的命令文件里我要求它先列出被测函数的“输入输出契约”再写用例用例要覆盖正常、边界、异常三类并且每条注明“防的是什么回归”--- description: 为指定模块生成单元测试覆盖正常、边界、异常路径 argument-hint: [模块路径] --- 请为 $ARGUMENTS 编写单元测试 1. 先列出被测函数的输入输出契约和边界条件 2. 用本项目的测试框架风格编写测试不确定就问不要假设 3. 覆盖三类用例正常路径、边界值空值/极值/超长、异常路径错误输入、超时、依赖失败 4. 每个用例注明它防的是什么回归 只生成新增测试文件不要改动被测源码。完成后给出运行测试的命令。“不要假设测试框架”这句很关键。Claude 经常默认你在用 Jest结果项目是 Mocha默认用 pytest结果是 unittest。命令里强制它先看项目现有测试风格能省掉大量返工。/提交信息读 git diff 生成规范提交信息--- description: 根据 git diff 生成符合规范的中文提交信息 argument-hint: [可选的改动意图说明] --- 请查看当前分支的 git diff 和暂存区生成一条符合 Conventional Commits 的中文提交信息 1. 先总结改动的主题一句话再按“新增/修改/修复/重构/文档/测试/性能”分类 2. 每条改动用一句话说明动机不要只罗列文件名 3. 如果 diff 超过 300 行按逻辑拆成多条建议提交 4. 直接输出提交信息文本不要添加解释。$ARGUMENTS 作为手动补充的上下文一并考虑这个命令看起来不起眼但每天坚持用git log 的可读性会彻底改善。代码写得好不好另说至少半年后回看提交历史能一眼知道当时在做什么。/接口文档从源码生成接口文档--- description: 根据源码生成或更新接口文档 argument-hint: [接口文件或路由前缀] --- 请阅读 $ARGUMENTS 相关的路由/函数定义生成接口文档 1. 对每个接口标注方法、路径、鉴权方式、请求参数名称/类型/是否必填/默认值/约束、响应结构、错误码 2. 用示例请求和响应体演示正常与异常场景 3. 整理成 Markdown 表格用中文说明 4. 如果发现接口行为与注释矛盾以代码为准并高亮提示/建项目是最重的一个命令它让 Claude 先规划目录和文件清单等确认后再动手--- description: 根据需求生成项目骨架、依赖清单和 README argument-hint: [项目名技术栈功能描述] --- 请初始化一个新项目需求$ARGUMENTS 1. 先规划目录结构、技术选型和关键依赖版本用表格展示 2. 生成最小可运行骨架入口文件、配置文件、示例模块 3. 生成 README.md项目简介、启动步骤、目录说明、环境变量 4. 列出初期里程碑和每个里程碑的验收标准 优先保证骨架能跑通不要生成花哨但无法集成的代码。生成前先列出文件清单等确认后再写。“先列文件清单等确认”这个设计是为了防止 Claude 一口气生成 40 个文件其中一半是垃圾。默认让它先亮出计划人看一眼同意后再执行产出质量明显更高。3. 安装与配置实操把命令包跑起来3.1 安装 Claude Code 与配置密钥先把 Claude Code 本体装好。前提是机器上有 Node.js版本建议 18 以上。我用 npm 全局安装npm install -g anthropic-ai/claude-code装完验证一下claude --version能输出版本号就说明安装成功。接下来配置认证。Claude Code 支持多种认证方式我这里用的是 Anthropic API 密钥把密钥放进环境变量里然后启动export ANTHROPIC_API_KEY你的密钥 claude也可以在交互界面里运行/login它会引导你完成认证。认证成功后在对话里输入/status能看到当前身份和模型信息确认无误就说明环境通了。这一步遇到最多的问题有两个一是 PATH 没生效npm 全局安装完claude命令找不到多半是 npm 全局 bin 目录没进 PATH运行npm bin -g看一下路径再加进去就行二是密钥配置了但没生效优先检查环境变量名是不是写成了ANTHROPIC_API_KEY少一个字母都不行。3.2 命令目录项目级、用户级、还有团队级命令文件不是只能放一个地方。Claude Code 支持三层作用域按优先级从低到高分别是用户级、企业级、项目级。用户级目录~/.claude/commands/放在这里的所有项目都能用。我放的是通用性最强的命令比如/提交信息、/解释报错任何项目都用得上。项目级目录.claude/commands/跟着仓库走提交到 git 后团队成员都能共享。我放的是和业务强相关的命令谁动了谁受益。企业级策略由企业管理员统一下发一般绑定内部认证体系个人开发者用不到。建议的做法是纯通用的命令放用户级和项目相关的放项目级。我见过有人把所有命令都塞进用户级目录结果换一台电脑、或者在 CI 环境里团队其他人根本拉不到这些命令等于白做。命令文件目录按名字排序展示中文命令按拼音排。比如/修Bug会在/写测试前面因为 X 的拼音 x 在写 xie 前面。第一版我把命令名全设计成了/bug-fix这种英文名在命令列表里排得乱七八糟换成中文后反而顺眼多了。3.3 用 CLAUDE.md 给命令补足项目上下文命令文件解决的是“怎么做”的问题但 Claude 还需要知道“这个项目是什么”。这个信息来自 CLAUDE.md 记忆文件。Claude Code 会自动读取项目根目录、用户目录下的记忆文件把里面的内容作为长期上下文。我现在在每个项目的.claude/CLAUDE.md里写这些内容项目技术栈和目录结构、代码风格约定、测试命令、构建命令、常用的环境变量以及“这个项目最近踩过的坑”。比如# 项目说明 - 后端Python FastAPI前端Vue 3 Vite - 测试命令pytest tests/ -q - 代码风格类型注解必写函数名用动词开头 - 已知坑缓存模块的 Redis 超时时间统一从配置读取不要硬编码这样/修Bug在定位问题时能自动结合 CLAUDE.md 里的约定不会给出一个违背项目惯例的修复方案。命令和记忆文件的关系就像“流程规范”和“项目档案”一个管步骤一个管背景两者配合才完整。实际测试中我有个体会让命令“更懂项目”的关键不是把命令写得多长而是把项目信息喂进 CLAUDE.md。命令正文保持短小项目相关的细节全部外置复用性和可维护性都会好很多。3.4 一个命令从敲下到出结果的完整流程以/审查代码 src/utils.ts为例走一遍完整生命周期。输入命令后Claude Code 先在.claude/commands里找到审查代码.md读取 YAML 前置信息里的description并在斜杠命令列表里展示。随后把整个命令正文加载进上下文$ARGUMENTS被替换成src/utils.ts。接下来进入执行阶段。Claude Code 会判断需要哪些工具先Read读文件再Grep或Glob搜索相关引用因为命令里提到了“搜索代码”然后按照正文要求的格式组织报告最后把结果打印到终端。此时命令正文的约束一直在起作用“不要直接改写全部文件”“先报告”——所以即使 Claude 有能力用Edit去改文件正文也拦住它了。整条链路里人只需要做一件事在命令触发后检查输出是否满足预期不满意就补一句追问满意就进入下一个命令。我自己的日常流程经常是这样的连环操作/读代码理解现状/审查代码找问题/修Bug改掉严重项/写测试补回归/提交信息出提交信息/接口文档同步文档。五个命令串下来一个功能从理解到落地到留痕全程有章可循。4. 实战中遇到的常见问题与排查4.1 命令不生效权限、路径与格式三大坑用命令包最沮丧的时刻就是敲了/命令名结果没有任何反应。我整理了一张速查表基本覆盖了我遇到过的所有情况现象可能原因处理方法敲 / 看不到任何自定义命令命令目录找错了确认项目级是.claude/commands/用户级是~/.claude/commands/命令列表能看到但选中后无输出文件不是 UTF-8 编码用 UTF-8 重新保存文件命令名是乱码或无法输入终端没有开启 UTF-8 支持检查终端编码设置选中命令后报 YAML 错误前置信息格式错误description没有写、冒号后漏了空格、参数 hint 里用了中文引号命令能触发但行为不对命令正文有 4 空格缩进被当作 YAML前置信息和正文之间的---要顶格正文不要缩进文件在但命令始终不出现文件扩展名不是.mdClaude Code 只识别.md文件第一周我自己掉进过两次“前置信息里中文引号”的坑。YAML 里argument-hint: [文件路径]的冒号后面必须跟半角空格也不能把[... ]输成全角。出现这类问题最直接的排查方式是用claude --debug启动看命令加载时的日志输出它会直接把加载失败的原因打出来。还有一个比较隐蔽的坑命令名是中文时文件名不要带多余空格或下划线。修Bug.md和修Bug_v2.md是两个不同命令目录里堆久了会分不清我后来统一规则文件名就是命令名不要加版本号。4.2 参数没传进去$ARGUMENTS 的脾气命令里写好了$ARGUMENTS但实际使用时Claude 好像没收到参数。我试过几次后发现$ARGUMENTS和$1的语义是有细微差别的。$ARGUMENTS会把命令名后面所有的文字原样替换进正文适合“一段描述”式的参数比如/修Bug 登录模块在并发下偶发 500。$1、$2则会按空格分词适合“多个独立参数”比如/写测试 src/utils.ts src/apis.ts。踩过的坑是参数里如果带空格或管道符容易被当成多个词。比如/解释报错 TypeError: Cannot read properties of undefined这种带冒号的报错语句有时候会截断。稳妥做法是把整个参数用引号包起来/解释报错 TypeError: Cannot read properties of undefined (reading name)。另外如果你在命令正文里同时写了$ARGUMENTS和别的文字注意替换是完全字符串替换不要指望 Claude 帮你“理解一下用户意图”。参数越明确输出越稳定这一条在命令设计时就要想清楚这个命令到底是接收一个路径还是接收一段自然语言描述。4.3 上下文爆炸与输出截断命令用了一段时间最刁钻的问题是上下文管理。命令本身要占一定的上下文空间CLAUDE.md 也要占再加上它读了几个大文件很快 20 万 token 的窗口就不够用了后面输出质量明显下降。我总结了几条实用对策。第一命令正文里明确写明“超过 X 行先讲骨架”这是上游拦截。第二让 Claude 在回答前先列“文件清单”再决定读哪些避免一次读十个大文件。第三项目 CLAUDE.md 保持精简只写不可推断的信息比如“这个模块的缓存规则很特殊”不要把 README 整段抄进去。输出截断也有招。当 Claude 生成的内容很长写到一半被窗口截断时我一般会补一句“用表格概括上面前三条结论”或者“每项限制在 20 字以内”。与其让它从头重写一遍浪费 token不如把已有输出改为结构化摘要。命令正文里如果预先把“输出为表格”写死遇到长报告时截断概率会低很多。4.4 命令越权乱改代码怎么办AI 改代码最怕的是它“好心办坏事”。命令写得再仔细Claude 在具体执行时也可能偏离尤其当它判断“这里顺手优化一下更好”的时候。解决思路分三层。第一层是约束工具权限在 YAML 前置信息里加allowed-tools只允许它读文件和搜索禁止写操作。比如/审查代码明确只读绝不给它Edit、Write权限想改代码就必须走/修Bug。第二层是命令正文要求“先报告方案等确认”这个在前面已经反复强调。第三层是实操兜底跑任何改代码类的命令前先git commit当前状态或者至少git stash这样即使 Claude 改坏了也能马上回滚。我建议所有改代码类命令都加上allowed-tools限制。比如/修Bug可以给Read、Grep、Glob、Edit、Write但/重构我还会收紧一点只允许它在确认后一次性写入。工具权限是 Claude Code 提供的硬性护栏比提示词里的“不要乱改”可靠得多。5. 实测记录与后续迭代方向5.1 一次完整的“修 Bug 补测试 出文档”实测说一个最近一次实战。项目里有个订单导出接口同事反馈偶尔会出现金额对不上的情况。我在 Claude Code 里敲/修Bug 订单导出接口在数据量超过一万条时统计金额偶发不一致Claude 先读了相关模块输出诊断报告导出用的是分页查询但统计金额的 SQL 和导出 SQL 用了两个不同的事务连接中间如果插入新订单就会出现“导出明细”和“统计金额”对不上的情况。它给的修复方案是让两条查询共享同一个读事务视图改动量只有 6 行。我看过根因分析后让它执行修复。随后我敲/写测试让它给导出模块补一个“分页期间新增订单”的回归测试用例。它先翻了项目测试目录发现项目用的是 pytest于是生成了一份符合项目风格的用例。最后我运行pytest -q新用例通过旧的也全绿。整套流程下来从发现问题到回归验证大概不到二十分钟中间我只做了三次确认。如果纯手写这个场景至少要翻代码定位问题、验证并发事务逻辑、手写测试用例、跑测试排查环境、再补测试数据。没有两三个小时下不来。命令包最大的贡献不是省打字而是把每一步的“思考框架”提前写好了我只需要做判断题和最终决策。5.2 我还在打磨的进阶玩法命令包稳定之后我开始琢磨几件更进阶的事。第一个是 hooks。Claude Code 支持在代码提交前、对话开始前、对话结束后触发自定义脚本。我打算把/提交信息生成的提交信息和 git 的pre-commithook 联动半自动完成“提交信息规范化”再把POST_TOOL_USE挂到编辑器上让每次Edit之后自动跑一遍相关单测把回归风险前置。目前还是实验阶段但方向是明确的命令负责“某个任务怎么做”hooks 负责“整个工作流怎么自动流转”。第二个是 subagents 多智能体协作。最近在尝试把命令拆成更小的专业角色比如审查员、测试员、文档员让主对话先拆解任务再分别派给各 subagent 执行最后统一汇总。这个玩法比较新效果还不稳定但它代表了一个方向命令迟早会从“单次调用的提示词模板”演进成“可编排的智能体工作流”。我的做法是先保持现有 10 个命令稳定可用再把它们逐个改造成可被 subagent 调用的独立任务单元。第三个是命令包的版本管理。因为我用了中文文件名git 对中文文件名的处理在不同系统下有差异我统一在仓库里放了一个README.md说明每个命令的作用和适用场景并在命令文件里写上版本号注释。这样团队里有人改了命令另一个成员 pull 下来能立刻知道变化不至于出现“你用的命令和我用的命令行为不一样”的混乱。5.3 一点个人体会这 10 个命令从第一版到现在前前后后改了大概五轮每一次修改都是因为某个真实场景的失败反馈。最后我想说一个体会命令的价值不在于写得多漂亮而在于你愿意持续用它并在用的时候不断修正它。AI 编程提示词、工作流这类东西本质上是把一个人的判断和习惯沉淀成可执行的模板模板越用越准。如果你也想搭一套自己的命令包别一上来追求数量先挑 3 个你最痛的任务写出来用两周再按真实反馈改效果会比一次性堆 20 个命令好得多。 Claude Code 中文斜杠命令包：10个命令打造AI编程标准工作流
说实话Claude Code 用久了最让我上瘾的不是它聊天多聪明而是那套斜杠命令机制。我花了两三个星期往.claude/commands目录里陆续塞了 10 个中文命令把读代码、审代码、改 Bug、写测试、补文档这些高频动作全部固化成了标准流程。这套 AI 编程工作流包现在每天跟着我跑项目帮我省下了大量重复敲提示词的时间也让团队新同学上手项目时不再两眼一抹黑。这篇文章就把这 10 个命令的完整内容、设计思路、安装配置流程和实际踩过的坑一次讲清楚。适合已经在用 Claude Code、或者正准备入坑、想把命令行 AI 从“随问随答”升级成“标准化流水线”的开发者参考。1. 为什么要给 Claude Code 造一套中文命令1.1 斜杠命令Claude Code 里最被低估的功能很多人把 Claude Code 当成一个挂在终端里的聊天窗口想到什么问什么。这种用法没问题但效率其实只发挥了三成。Claude Code 真正的杀手锏是它支持用户自定义斜杠命令Slash Command你在终端里敲/就能呼出一个命令列表选中之后Claude 会按照命令文件里预写好的提示词去执行任务。这套机制的本质是把“每次都要重复输入一大段提示词”变成“敲两个字符就搞定”。比如你想让我审查代码不需要再打一遍“请你以资深工程师视角检查这个文件的安全性、性能、可维护性”只需要输入/审代码 src/auth.ts剩下的事情命令文件替你安排。命令文件就是普通的 Markdown 文件放在.claude/commands目录下文件名就是命令名内容最前面是 YAML 格式的前置信息后面是命令正文正文里可以用$ARGUMENTS、$1、$2这些占位符接收用户输入。Claude 在收到/命令名 参数时会把命令文件整体加载进上下文再把参数替换进去最后按照正文里的指示执行。整个过程涉及读文件、写文件、跑命令时Claude 会自主调用自己的工具不需要你手把手指挥。我觉得这个功能被严重低估了。提示词写得好Claude Code 的输出质量和稳定性会提升一大截把提示词固化成命令就等于把“某类任务的最佳做法”沉淀到了工作流里团队里的人都能复用不用每个人各自发挥。1.2 中文命令解决了谁的痛点我认识不少开发者英文读写没问题但和人交流、写需求文档、看内部资料时脑子里第一反应还是中文。这种情况下如果你用的命令和提示词全是英文每次触发前都要先在脑子里“翻译”一遍命令一多反而成了负担。中文命令最直接的好处是降低认知成本。命令名用中文看到/读代码、/修Bug你不需要回忆这个命令是干嘛的光看名字就知道用途。命令输出也用中文评审意见、Bug 诊断、接口文档这些交付物可以直接贴进中文团队的需求单和缺陷管理系统不用二次转换。这个设计对团队协作尤其有价值。我现在的工作流里新同学接手一个陌生仓库第一件事就是敲/读代码让 Claude 把入口、数据流、核心模块讲一遍Code Review 之前统一走/审查代码保证每个人的审查标准一致。命令文件放在项目仓库里随 git 走新人 clone 下来就自动有了全套命令这才是把“个人技巧”变成“团队资产”的正确姿势。1.3 这套命令包的设计原则在动手写命令之前我先给自己定了几条规矩这几条直接决定了命令包好不好用。第一一个命令只干一件完整的事。审查代码就是审查代码不要顺便把修 Bug 也干了生成接口文档就只生成文档不要顺手改代码。混在一起会让输出变得不可控也不方便事后校验。第二改代码类命令默认“先诊断、后动手”。比如/修Bug我要求它先输出根因分析报告确认了再改/重构必须保持行为不变。AI 改代码最怕的就是“自信地改错”强制加一道确认环节能避免大量事故。第三输出格式标准化。凡是会产出报告的都要求用表格、分级列表、固定章节。这样我扫一眼就能定位重点不用在一大段散文里找结论。第四控制上下文消耗。命令正文里我会明确限制“如果代码量超过多少行先讲骨架”防止 Claude 一口气读太多文件把上下文预算烧光导致后半程回答质量断崖式下降。这几条原则看着简单但真写命令时特别容易违反尤其是“顺手多做一步”。我前几版命令里就混入过“顺便优化一下”后来全改掉了。2. 10 个中文命令逐个拆解2.1 先看命令文件长什么样命令文件是 Markdown 格式开头用两行---包起来的是 YAML 前置信息至少要有description建议加上argument-hint需要限制工具时加allowed-tools。后面是正文正文里可以放$ARGUMENTS、$1、$2等占位符接收用户敲的参数。拿我最常用的/修Bug举例完整命令文件长这样--- description: 定位并修复指定 Bug先给诊断报告再改代码 argument-hint: [Bug 现象描述或相关文件路径] --- 你是经验丰富的调试工程师。针对 $ARGUMENTS 1. 先复现问题判断是输入数据、边界条件还是并发时序导致 2. 给出一份诊断报告根因、影响范围、触发条件、证据链 3. 提出修复方案默认选最小改动方案说明为什么不动其他代码 4. 修复后列出需要补充的回归测试用例 在没有确认根因之前绝对不要乱改代码。如果信息不足以定位直接列出需要补充的信息和日志。这里有两个细节值得注意。$ARGUMENTS会替换成用户在/修Bug后面输入的全部内容可以是描述也可以是文件路径。正文最后那句“绝对不要乱改代码”不是废话Claude 这类模型在任务压力下很容易“表现欲上头”直接给出一个大改方案必须有书面约束。文件保存为.claude/commands/修Bug.md在 Claude Code 里敲/修Bug命令就出来了。项目级命令、用户级命令、企业级命令的位置有区别这个我在第三章细讲。2.2 读代码类读懂别人项目的三个命令第一组命令解决的是“读”的问题/读代码、/审查代码、/解释报错。/读代码的核心是让 Claude 当导师。我看过太多介绍代码的提示词要求“详细讲解”结果 Claude 把每个函数都念一遍读完等于没读。所以我故意加了约束超过 500 行先讲骨架而且必须讲清楚数据流和副作用。命令正文是这样--- description: 解释指定目录/文件的核心逻辑生成阅读导图 argument-hint: [目标路径] --- 请扮演一位耐心的导师用通俗易懂的方式讲解 $ARGUMENTS 1. 先说明整体架构入口在哪数据流怎么走外部依赖有哪些 2. 按调用链拆解核心函数讲清楚输入、输出、副作用 3. 标记最值得注意的坑隐藏全局状态、隐式转换、时序依赖 4. 最后用文本流程图描述主线流程 如果代码量大于 500 行优先讲解骨架和关键路径不要逐行啰嗦。/审查代码走的是另一个方向它产出的是问题清单不是讲解--- description: 审查代码质量、安全隐患和坏味道输出分级问题清单 argument-hint: [文件或目录路径] --- 你是一名严谨的资深代码审查员。请审查 $ARGUMENTS重点检查 1. 逻辑错误与边界条件遗漏 2. 安全隐患注入、越权、敏感信息泄露 3. 性能隐患N1 查询、无谓循环、内存泄漏 4. 可维护性问题命名、重复代码、注释与实现不符 输出格式按“严重/建议/可选”三级分组每条给出文件位置、原因说明和修改建议最后用代码块给出关键修改示例。先报告不要直接改写全部文件。/解释报错是救急用的。遇到一串陌生报错与其复制去搜索引擎不如直接粘给这个命令--- description: 翻译并定位错误日志/异常堆栈 argument-hint: [粘贴报错信息] --- 请解读以下报错信息$ARGUMENTS 1. 用一句话说清楚错误本质不要只翻译原文 2. 列出最常见的 3 个触发原因按概率排序 3. 结合报错堆栈定位本项目可能的出错位置必要时搜索代码 4. 给出排查命令建议复现请求、调整日志级别、补单测用例这三个命令设计时有个共同点都强制要求输出结构化结果要么是“骨架关键路径”要么是“分级清单”要么是“一句话本质概率排序”。因为读代码的场景里我真正需要的是快速形成心智模型而不是一篇优美的代码赏析。2.3 改代码类修 Bug、重构、做性能分析第二组命令解决“改”的问题也是最容易翻车的部分。/修Bug我在 2.1 已经展示过这里重点说它和最怕发生的事——AI 猜一个原因就直接改。所以我特意要求“先诊断后修复”并且提示词里写了“没有确认根因之前绝对不要乱改代码”。/重构的命令文件把“行为不变”当成铁律--- description: 对指定模块进行小步重构保持行为不变 argument-hint: [目标文件路径] --- 请对 $ARGUMENTS 进行行为不变的重构 1. 先量化描述当前问题圈复杂度、重复代码比例、函数长度、耦合点 2. 给出重构计划按小步执行每步必须可独立测试 3. 优先消除重复代码、过长函数、深层嵌套、全局可变状态 4. 完成后列出行为等价性的验证方法现有测试/临时对比脚本 严禁在重构过程中顺手修改业务逻辑如果你觉得某个改动会改变行为停下来单独说明。这里藏着一条经验“小步执行每步可独立测试”听起来像流水账但对大模型特别重要。一次丢给它一个 800 行的老模块让它重构它大概率会给你一个“全新的、看起来更好但行为变了”的版本逼它分步走每一步都能验证风险就小很多。/性能分析则强调用数据说话--- description: 从代码层面分析性能瓶颈并给出优化建议 argument-hint: [目标文件或接口路径] --- 以性能工程师视角分析 $ARGUMENTS 1. 先建立基线这段代码的时间复杂度、空间复杂度热点在哪 2. 检查常见性能陷阱循环内 IO、重复计算、不必要拷贝、锁竞争、缓存失效 3. 按“收益/成本比”排序优化建议先写收益大改动小的 4. 每条建议写明预期提升量级常数倍/线性/数量级不要给没有数据的空泛思路 如果无法从静态代码判断指明需要补充的 profiling 数据。我吃过不少亏让 AI 优化性能它把for循环改成map然后说“性能提升”实际上根本没变化。所以这个命令必须要求“预期提升量级”写不出来就说明它没有把握我会直接跳过。2.4 交付物类写测试、提交信息、接口文档、搭骨架剩下四个命令负责“输出交付物”它们共同的特点是产出物直接可用不需要大改。/写测试的命令文件里我要求它先列出被测函数的“输入输出契约”再写用例用例要覆盖正常、边界、异常三类并且每条注明“防的是什么回归”--- description: 为指定模块生成单元测试覆盖正常、边界、异常路径 argument-hint: [模块路径] --- 请为 $ARGUMENTS 编写单元测试 1. 先列出被测函数的输入输出契约和边界条件 2. 用本项目的测试框架风格编写测试不确定就问不要假设 3. 覆盖三类用例正常路径、边界值空值/极值/超长、异常路径错误输入、超时、依赖失败 4. 每个用例注明它防的是什么回归 只生成新增测试文件不要改动被测源码。完成后给出运行测试的命令。“不要假设测试框架”这句很关键。Claude 经常默认你在用 Jest结果项目是 Mocha默认用 pytest结果是 unittest。命令里强制它先看项目现有测试风格能省掉大量返工。/提交信息读 git diff 生成规范提交信息--- description: 根据 git diff 生成符合规范的中文提交信息 argument-hint: [可选的改动意图说明] --- 请查看当前分支的 git diff 和暂存区生成一条符合 Conventional Commits 的中文提交信息 1. 先总结改动的主题一句话再按“新增/修改/修复/重构/文档/测试/性能”分类 2. 每条改动用一句话说明动机不要只罗列文件名 3. 如果 diff 超过 300 行按逻辑拆成多条建议提交 4. 直接输出提交信息文本不要添加解释。$ARGUMENTS 作为手动补充的上下文一并考虑这个命令看起来不起眼但每天坚持用git log 的可读性会彻底改善。代码写得好不好另说至少半年后回看提交历史能一眼知道当时在做什么。/接口文档从源码生成接口文档--- description: 根据源码生成或更新接口文档 argument-hint: [接口文件或路由前缀] --- 请阅读 $ARGUMENTS 相关的路由/函数定义生成接口文档 1. 对每个接口标注方法、路径、鉴权方式、请求参数名称/类型/是否必填/默认值/约束、响应结构、错误码 2. 用示例请求和响应体演示正常与异常场景 3. 整理成 Markdown 表格用中文说明 4. 如果发现接口行为与注释矛盾以代码为准并高亮提示/建项目是最重的一个命令它让 Claude 先规划目录和文件清单等确认后再动手--- description: 根据需求生成项目骨架、依赖清单和 README argument-hint: [项目名技术栈功能描述] --- 请初始化一个新项目需求$ARGUMENTS 1. 先规划目录结构、技术选型和关键依赖版本用表格展示 2. 生成最小可运行骨架入口文件、配置文件、示例模块 3. 生成 README.md项目简介、启动步骤、目录说明、环境变量 4. 列出初期里程碑和每个里程碑的验收标准 优先保证骨架能跑通不要生成花哨但无法集成的代码。生成前先列出文件清单等确认后再写。“先列文件清单等确认”这个设计是为了防止 Claude 一口气生成 40 个文件其中一半是垃圾。默认让它先亮出计划人看一眼同意后再执行产出质量明显更高。3. 安装与配置实操把命令包跑起来3.1 安装 Claude Code 与配置密钥先把 Claude Code 本体装好。前提是机器上有 Node.js版本建议 18 以上。我用 npm 全局安装npm install -g anthropic-ai/claude-code装完验证一下claude --version能输出版本号就说明安装成功。接下来配置认证。Claude Code 支持多种认证方式我这里用的是 Anthropic API 密钥把密钥放进环境变量里然后启动export ANTHROPIC_API_KEY你的密钥 claude也可以在交互界面里运行/login它会引导你完成认证。认证成功后在对话里输入/status能看到当前身份和模型信息确认无误就说明环境通了。这一步遇到最多的问题有两个一是 PATH 没生效npm 全局安装完claude命令找不到多半是 npm 全局 bin 目录没进 PATH运行npm bin -g看一下路径再加进去就行二是密钥配置了但没生效优先检查环境变量名是不是写成了ANTHROPIC_API_KEY少一个字母都不行。3.2 命令目录项目级、用户级、还有团队级命令文件不是只能放一个地方。Claude Code 支持三层作用域按优先级从低到高分别是用户级、企业级、项目级。用户级目录~/.claude/commands/放在这里的所有项目都能用。我放的是通用性最强的命令比如/提交信息、/解释报错任何项目都用得上。项目级目录.claude/commands/跟着仓库走提交到 git 后团队成员都能共享。我放的是和业务强相关的命令谁动了谁受益。企业级策略由企业管理员统一下发一般绑定内部认证体系个人开发者用不到。建议的做法是纯通用的命令放用户级和项目相关的放项目级。我见过有人把所有命令都塞进用户级目录结果换一台电脑、或者在 CI 环境里团队其他人根本拉不到这些命令等于白做。命令文件目录按名字排序展示中文命令按拼音排。比如/修Bug会在/写测试前面因为 X 的拼音 x 在写 xie 前面。第一版我把命令名全设计成了/bug-fix这种英文名在命令列表里排得乱七八糟换成中文后反而顺眼多了。3.3 用 CLAUDE.md 给命令补足项目上下文命令文件解决的是“怎么做”的问题但 Claude 还需要知道“这个项目是什么”。这个信息来自 CLAUDE.md 记忆文件。Claude Code 会自动读取项目根目录、用户目录下的记忆文件把里面的内容作为长期上下文。我现在在每个项目的.claude/CLAUDE.md里写这些内容项目技术栈和目录结构、代码风格约定、测试命令、构建命令、常用的环境变量以及“这个项目最近踩过的坑”。比如# 项目说明 - 后端Python FastAPI前端Vue 3 Vite - 测试命令pytest tests/ -q - 代码风格类型注解必写函数名用动词开头 - 已知坑缓存模块的 Redis 超时时间统一从配置读取不要硬编码这样/修Bug在定位问题时能自动结合 CLAUDE.md 里的约定不会给出一个违背项目惯例的修复方案。命令和记忆文件的关系就像“流程规范”和“项目档案”一个管步骤一个管背景两者配合才完整。实际测试中我有个体会让命令“更懂项目”的关键不是把命令写得多长而是把项目信息喂进 CLAUDE.md。命令正文保持短小项目相关的细节全部外置复用性和可维护性都会好很多。3.4 一个命令从敲下到出结果的完整流程以/审查代码 src/utils.ts为例走一遍完整生命周期。输入命令后Claude Code 先在.claude/commands里找到审查代码.md读取 YAML 前置信息里的description并在斜杠命令列表里展示。随后把整个命令正文加载进上下文$ARGUMENTS被替换成src/utils.ts。接下来进入执行阶段。Claude Code 会判断需要哪些工具先Read读文件再Grep或Glob搜索相关引用因为命令里提到了“搜索代码”然后按照正文要求的格式组织报告最后把结果打印到终端。此时命令正文的约束一直在起作用“不要直接改写全部文件”“先报告”——所以即使 Claude 有能力用Edit去改文件正文也拦住它了。整条链路里人只需要做一件事在命令触发后检查输出是否满足预期不满意就补一句追问满意就进入下一个命令。我自己的日常流程经常是这样的连环操作/读代码理解现状/审查代码找问题/修Bug改掉严重项/写测试补回归/提交信息出提交信息/接口文档同步文档。五个命令串下来一个功能从理解到落地到留痕全程有章可循。4. 实战中遇到的常见问题与排查4.1 命令不生效权限、路径与格式三大坑用命令包最沮丧的时刻就是敲了/命令名结果没有任何反应。我整理了一张速查表基本覆盖了我遇到过的所有情况现象可能原因处理方法敲 / 看不到任何自定义命令命令目录找错了确认项目级是.claude/commands/用户级是~/.claude/commands/命令列表能看到但选中后无输出文件不是 UTF-8 编码用 UTF-8 重新保存文件命令名是乱码或无法输入终端没有开启 UTF-8 支持检查终端编码设置选中命令后报 YAML 错误前置信息格式错误description没有写、冒号后漏了空格、参数 hint 里用了中文引号命令能触发但行为不对命令正文有 4 空格缩进被当作 YAML前置信息和正文之间的---要顶格正文不要缩进文件在但命令始终不出现文件扩展名不是.mdClaude Code 只识别.md文件第一周我自己掉进过两次“前置信息里中文引号”的坑。YAML 里argument-hint: [文件路径]的冒号后面必须跟半角空格也不能把[... ]输成全角。出现这类问题最直接的排查方式是用claude --debug启动看命令加载时的日志输出它会直接把加载失败的原因打出来。还有一个比较隐蔽的坑命令名是中文时文件名不要带多余空格或下划线。修Bug.md和修Bug_v2.md是两个不同命令目录里堆久了会分不清我后来统一规则文件名就是命令名不要加版本号。4.2 参数没传进去$ARGUMENTS 的脾气命令里写好了$ARGUMENTS但实际使用时Claude 好像没收到参数。我试过几次后发现$ARGUMENTS和$1的语义是有细微差别的。$ARGUMENTS会把命令名后面所有的文字原样替换进正文适合“一段描述”式的参数比如/修Bug 登录模块在并发下偶发 500。$1、$2则会按空格分词适合“多个独立参数”比如/写测试 src/utils.ts src/apis.ts。踩过的坑是参数里如果带空格或管道符容易被当成多个词。比如/解释报错 TypeError: Cannot read properties of undefined这种带冒号的报错语句有时候会截断。稳妥做法是把整个参数用引号包起来/解释报错 TypeError: Cannot read properties of undefined (reading name)。另外如果你在命令正文里同时写了$ARGUMENTS和别的文字注意替换是完全字符串替换不要指望 Claude 帮你“理解一下用户意图”。参数越明确输出越稳定这一条在命令设计时就要想清楚这个命令到底是接收一个路径还是接收一段自然语言描述。4.3 上下文爆炸与输出截断命令用了一段时间最刁钻的问题是上下文管理。命令本身要占一定的上下文空间CLAUDE.md 也要占再加上它读了几个大文件很快 20 万 token 的窗口就不够用了后面输出质量明显下降。我总结了几条实用对策。第一命令正文里明确写明“超过 X 行先讲骨架”这是上游拦截。第二让 Claude 在回答前先列“文件清单”再决定读哪些避免一次读十个大文件。第三项目 CLAUDE.md 保持精简只写不可推断的信息比如“这个模块的缓存规则很特殊”不要把 README 整段抄进去。输出截断也有招。当 Claude 生成的内容很长写到一半被窗口截断时我一般会补一句“用表格概括上面前三条结论”或者“每项限制在 20 字以内”。与其让它从头重写一遍浪费 token不如把已有输出改为结构化摘要。命令正文里如果预先把“输出为表格”写死遇到长报告时截断概率会低很多。4.4 命令越权乱改代码怎么办AI 改代码最怕的是它“好心办坏事”。命令写得再仔细Claude 在具体执行时也可能偏离尤其当它判断“这里顺手优化一下更好”的时候。解决思路分三层。第一层是约束工具权限在 YAML 前置信息里加allowed-tools只允许它读文件和搜索禁止写操作。比如/审查代码明确只读绝不给它Edit、Write权限想改代码就必须走/修Bug。第二层是命令正文要求“先报告方案等确认”这个在前面已经反复强调。第三层是实操兜底跑任何改代码类的命令前先git commit当前状态或者至少git stash这样即使 Claude 改坏了也能马上回滚。我建议所有改代码类命令都加上allowed-tools限制。比如/修Bug可以给Read、Grep、Glob、Edit、Write但/重构我还会收紧一点只允许它在确认后一次性写入。工具权限是 Claude Code 提供的硬性护栏比提示词里的“不要乱改”可靠得多。5. 实测记录与后续迭代方向5.1 一次完整的“修 Bug 补测试 出文档”实测说一个最近一次实战。项目里有个订单导出接口同事反馈偶尔会出现金额对不上的情况。我在 Claude Code 里敲/修Bug 订单导出接口在数据量超过一万条时统计金额偶发不一致Claude 先读了相关模块输出诊断报告导出用的是分页查询但统计金额的 SQL 和导出 SQL 用了两个不同的事务连接中间如果插入新订单就会出现“导出明细”和“统计金额”对不上的情况。它给的修复方案是让两条查询共享同一个读事务视图改动量只有 6 行。我看过根因分析后让它执行修复。随后我敲/写测试让它给导出模块补一个“分页期间新增订单”的回归测试用例。它先翻了项目测试目录发现项目用的是 pytest于是生成了一份符合项目风格的用例。最后我运行pytest -q新用例通过旧的也全绿。整套流程下来从发现问题到回归验证大概不到二十分钟中间我只做了三次确认。如果纯手写这个场景至少要翻代码定位问题、验证并发事务逻辑、手写测试用例、跑测试排查环境、再补测试数据。没有两三个小时下不来。命令包最大的贡献不是省打字而是把每一步的“思考框架”提前写好了我只需要做判断题和最终决策。5.2 我还在打磨的进阶玩法命令包稳定之后我开始琢磨几件更进阶的事。第一个是 hooks。Claude Code 支持在代码提交前、对话开始前、对话结束后触发自定义脚本。我打算把/提交信息生成的提交信息和 git 的pre-commithook 联动半自动完成“提交信息规范化”再把POST_TOOL_USE挂到编辑器上让每次Edit之后自动跑一遍相关单测把回归风险前置。目前还是实验阶段但方向是明确的命令负责“某个任务怎么做”hooks 负责“整个工作流怎么自动流转”。第二个是 subagents 多智能体协作。最近在尝试把命令拆成更小的专业角色比如审查员、测试员、文档员让主对话先拆解任务再分别派给各 subagent 执行最后统一汇总。这个玩法比较新效果还不稳定但它代表了一个方向命令迟早会从“单次调用的提示词模板”演进成“可编排的智能体工作流”。我的做法是先保持现有 10 个命令稳定可用再把它们逐个改造成可被 subagent 调用的独立任务单元。第三个是命令包的版本管理。因为我用了中文文件名git 对中文文件名的处理在不同系统下有差异我统一在仓库里放了一个README.md说明每个命令的作用和适用场景并在命令文件里写上版本号注释。这样团队里有人改了命令另一个成员 pull 下来能立刻知道变化不至于出现“你用的命令和我用的命令行为不一样”的混乱。5.3 一点个人体会这 10 个命令从第一版到现在前前后后改了大概五轮每一次修改都是因为某个真实场景的失败反馈。最后我想说一个体会命令的价值不在于写得多漂亮而在于你愿意持续用它并在用的时候不断修正它。AI 编程提示词、工作流这类东西本质上是把一个人的判断和习惯沉淀成可执行的模板模板越用越准。如果你也想搭一套自己的命令包别一上来追求数量先挑 3 个你最痛的任务写出来用两周再按真实反馈改效果会比一次性堆 20 个命令好得多。