每天打开终端准备干活时总是要先敲一大段背景说明再把代码路径和评审规则重复一遍最后还要祈祷AI不要天马行空乱发挥。这种状态持续一段时间后我决定不再当“人肉提示词复读机”而是把十多个反复使用的工程动作全部封装成 Claude Code 里一个个中文斜杠命令。这套“中文命令组成的 AI 编程工作流包”跑了一段时间实测下来非常稳也踩了不少坑。这篇文章就把我是怎么设计、装配、调试这 10 个中文命令的完整过程拆开讲清楚包括命令文件的组织方式、参数设计、常见报错排查以及那些文档里根本不会写的经验教训。如果你正在用 Claude Code 做日常开发又觉得每次重复构造提示词很浪费精力或者你希望团队新成员打开项目就能拥有统一的工作流那么这套命令包的设计思路可以直接参考。1. 中文命令包的设计思路为什么一定要把工作流沉淀成命令1.1 手写提示词和调用命令差在哪先讲一个特别常见的场景。今天你让AI跑一遍代码审查明天你想让它补测试用例后天你可能要解释一段别人写的烂代码。每一次你都得从头描述项目背景、技术栈、要看的文件、期望的输出格式。手写提示词不是不行问题是每次写的质量都飘忽不定。状态好的时候提示词写得很细AI输出就像模像样状态差的时候一句“帮我看看这段代码”AI只能给你一个非常泛的回复价值相当有限。做命令封装本质上是把“一次性的优秀提示词”变成“可重复调用的固化资产”。命令跑起来之后每次触发的都是同一套经过打磨的标准指令AI的输入质量不会因为你的精神状态而波动。这和做饭是一个道理你当然可以从买菜到切墩全程手动但只要你是天天吃预制好一份配料固定的菜包永远比临时发挥稳定。命令并不是什么黑魔法它就是预制菜包把工程中高频、重复、确定性高的环节提前打包。另一个关键差异在输出可预期性。手写提示词时AI的回复格式千奇百怪你还要人工整理。命令文件里写死输出模板后AI每次都会按同一个Markdown结构交付结果你可以直接把结果贴进任务拆解文档或者提交记录里几乎不用二次加工。这个体验一旦用过就很难回去了。1.2 十个命令的选型清单与分工逻辑选哪10个命令不是拍脑袋定的。我先把平时开发最常做的事列了一遍再按“分析—方案—实现—验证—提交”这条主线收敛最后留下了这 10 个命令名触发场景核心作用/需求分析需求描述模糊时把业务想法拆成功能列表、边界条件和验收标准/技术方案动手写码前生成技术选型、接口设计、数据模型和风险点/拆解任务方案确定后把开发目标拆成可逐个交付的编码任务列表/补全注释代码可读性差时为现有代码补充中文注释与模块文档/生成测试功能写完时按边界条件生成单元测试和用例说明/代码审查提交代码前从正确性、性能、安全隐患、可读性、可测试性五个维度审查/修复缺陷测试反馈问题时根据错误信息定位原因输出修复方案和改动/解释代码接手陌生模块时逐步讲解代码逻辑并输出调用关系/重构优化代码难改时保持行为不变的前提下改善结构降低维护成本/生成提交说明准备提交时按 git 变更内容生成规范化提交信息这 10 个命令不是孤立的它们可以像流水线一样串联。比如一个典型下午先写一段模糊的业务描述敲 /需求分析 把需求理清再敲 /技术方案 得到接口设计让AI完成编码后用 /生成测试 补齐测试提交前跑一遍 /代码审查最后用 /生成提交说明 快速产出 commit message。每个命令的输出是下一个命令的输入整条链路就顺了。1.3 中文优先的取舍什么时候该用中文命令可能有人会问Claude Code 本身就是英文提示词也能用为什么非要做成中文命令包我的回答是因为你的代码库、你的团队、你的业务文档说的是什么语言命令就该用什么语言。我们这这边的需求文档、拉取请求描述、代码注释都是中文为主AI 只有直接理解中文需求才能把“用户要求导出 Excel”和“退出登录后要跳首页”这种细节翻译成准确的技术任务。如果我先把它翻译成英文提示词再让 AI 做一轮英文思考最后把结果翻译回中文语义损耗非常大尤其是一些口语化业务描述翻成英文就变味了。但这事不是绝对的。如果你参与的是国际化开源项目所有 issue 和讨论都以英文进行那么输出命令反而应该用英文要求 AI 生成英文文档和英文 commit message。命令的语言要和团队的语言资产保持一致而不是为了“显得高级”刻意选英文或者刻意选中文。2. 命令文件怎么写目录、格式和中文指令的六要素2.1 命令存放位置与文件格式Claude Code 的自定义斜杠命令最常见的方式是在项目的 .claude 目录下建一个 commands 文件夹每个命令对应一个 Markdown 文件文件名就是命令名。我这里加了 10 个文件之后目录大概长这样.claude/ └── commands/ ├── 需求分析.md ├── 技术方案.md ├── 拆解任务.md ├── 补全注释.md ├── 生成测试.md ├── 代码审查.md ├── 修复缺陷.md ├── 解释代码.md ├── 重构优化.md └── 生成提交说明.md每个命令文件由两部分组成。顶部是配置区写一些元信息比如命令的描述、参数提示、可调用的能力范围等。不同版本的客户端字段写法可能会有差异以你自己装的那个版本为准。我自己的写法很朴素大致长这样--- description: 对当前代码变更做五维审查输出问题清单与修复建议 argument_hint: 可选指定审查范围例如 某文件路径 ---配置区下面就是正式的指令正文也就是每次触发命令时实际注入给 AI 的那段提示词内容用 Markdown 编写。整份文件既在你仓库里可追踪又能直接被工具加载。关于文件名用中文这件事我一开始是有顾虑的怕终端环境和编码不支持。实测之后发现我常用的环境里没问题。如果你那边敲了中文命令名没有联想或没反应大概率是编码或输入法的问题可以把文件名改成拼音或者英文例如 shen-cha.md正文和输出要求保持中文效果一样好。2.2 一份高质量中文指令的六个组成部分我拆解过很多失败的命令发现凡是 AI 输出稀烂的基本都因为指令文本里缺了下面这六样东西第一角色设定。别指望 AI 默认知道自己是“资深后端工程师”还是“测试开发”。命令一开头就写清楚“你是一位有十年经验的代码审查专家”这决定了整个回答的角度、专业性和术语体系。第二目标描述。用一两句话说明白这次命令是为了达成什么结果。比如“审查指定文件找出会导致线上事故或返工的问题”。没有目标AI 会平均用力输出大而全的废话。第三输入来源。明确建模该从哪拿数据是当前会话里用户贴的代码还是要用工具读取某个文件还是读取上下文里已有的结论。写清楚输入来源模型才不会乱翻项目文件。第四执行步骤。把任务拆成 3 到 6 个有序步骤让 AI 按顺序走。比如先读取文件结构再定位关键逻辑再逐个风险点分析最后汇总。步骤越清晰生成的中间思维过程越收敛。第五约束与禁忌。这一步最容易被忽略。你要主动告诉 AI 什么不要做不要修改代码、不要执行写操作、不要假设文件不存在、不要重复审查未指定的目录。约束比引导管用得多。第六输出格式。固定一个输出模板让 AI 照着填充。比如“先输出评分表再输出问题清单和对应的行号最后给修改建议”。输出格式固定之后命令的交付物才具备可复用性。2.3 用 /代码审查 做一次完整拆解拿我最常用的 /代码审查 举例我把上面六个要素全揉进了一个命令文件。命令正文大致是这个结构你是一位有十年经验的资深代码审查专家。请对目标代码进行五个维度的审查正确性、性能、安全隐患、可读性、可测试性。 输入 - 审查范围优先使用用户输入的参数如果没有给出参数则列出候选文件让用户确认不要擅自读取大量文件。 - 如果读取文件只读取与任务相关的内容不要读取整个代码仓库。 执行步骤 1. 先概览目标文件的结构和职责。 2. 逐段阅读核心逻辑找出明显的逻辑错误和边界条件遗漏。 3. 检查是否存在安全风险如注入、越权、敏感信息泄露。 4. 给出问题定位每个问题必须引用具体的文件名和行号。 5. 按严重程度从高到低排序输出。 输出格式严格按以下模板不要画蛇添足 ## 审查结论 - 整体评价一句话 ## 问题清单 | 严重程度 | 位置 | 问题描述 | 修复建议 | | --- | --- | --- | --- | ## 待确认假设 - 列出你在审查中无法确认、需要人来判断的假设这个命令的精髓其实不是那五个维度而是“待确认假设”这个输出项。它逼着 AI 在无法确定业务意图时主动暴露不确定性而不是编一个看似合理的判断糊弄你。我后来把所有命令都加了类似的“不确定项留白”区AI 输出的可信度提升非常明显。写命令的一大禁忌是试图在一条命令里塞进多个大任务。比如“审查并修复代码同时生成测试”这种命令大概率样样稀松。一条命令只做一件事做好就足够了。3. 实战演练用命令包装下一个完整功能的开发流程3.1 三步初始化建目录、写命令、验证加载第一次搭建这套命令包操作其实很快。第一步在项目根目录建好 .claude/commands/ 文件夹。第二步把准备好的命令文件填进去不用一次性写满 10 个我建议先写 3 个最痛的需求分析、生成测试、代码审查。第三步启动一个全新的会话输入斜杠时看一下命令列表里是否已经出现刚才写入的命令名。如果命令没有出现不要急着怀疑配置。先检查文件是不是真的在 .claude/commands/ 下确认后缀名是 .md再看看文件的编码是否是 UTF-8。很多时候只是上了个新文件客户端没热加载重开一个会话就解决了。验证通过之后再逐步把剩余命令补全。这里有个经验一定不要把命令文件直接放在 .claude/ 根目录下或者塞进子文件夹。某些版本只认 commands 目录下的一层文件放错位置就是隐形。最开始我就把命令放到 .claude/ 下结果过了半天才发现命令列表一直是空的。3.2 全程走查从需求拆解到提交说明为了说清楚这套命令包的真实手感我拿一个模拟项目 X 的“待办事项 API”小功能走一遍全流程。假设产品同学给了一句非常口语化的需求“我想做一个简单的待办清单 API用户可以增删查最好能标记已完成。”第一步我直接敲 /需求分析 待办事项 API。命令要求 AI 先提问题再输出功能列表、边界条件和验收标准。它很快产出了一份结构化的清单把“用户”细化为“注册用户和管理员”把“增删查”细化为“创建待办、修改标题、标记完成、删除、列表查询”还补了一个“已完成的待办自动归档”的边界规则。这个步骤的价值在于模糊想法经过命令的强制拆解变成了可讨论的技术输入。第二步我对需求清单点头后敲 /技术方案。它基于前面的分析结果输出了一版 API 设计REST 接口路径、请求响应结构、数据表字段、状态码约定。因为我给命令加了“先确认技术选型范围”的要求AI 没有擅自引入消息队列这类重型组件而是老老实实选了 SQLite 加一个轻量路由。第三步编码阶段我直接让 AI 在会话里写核心模块写完后执行 /生成测试。这个命令会读目标文件按边界条件生成单元测试。比如列表接口为空时怎么返回、标记已完成的任务重复标记是否报错、删除不存在 ID 时的行为。AI 生成的测试覆盖了这些边界只有一个用例因为业务规则理解偏差没通过我修了一行代码就全绿了。第四步提交前跑 /代码审查。它输出了 4 个问题其中一个是真实的隐患查询列表接口没有做分页上限数据量一大就会缓慢另一个是风格问题错误响应体结构不统一。我按它的建议改完再让 AI 重新审查确认第二次结果就只剩待确认假设列表了。最后一步敲 /生成提交说明。它拿到 git diff 后生成的 commit message 是“feat: 增加待办事项 CRUD 接口并补充边界测试”完全符合我们团队的规范。整个过程里我并没有每次手写长提示词只是把命令名和文件路径告诉 AI它就知道该怎么干。3.3 参数与上下文的控制策略命令包跑起来之后最容易翻车的地方不是命令本身而是上下文控制。很多 AI 编程工具能读文件但读文件也是有成本的一条命令如果默认“读取整个项目后分析”大概率会在超量上下文里失去重点输出一堆无关紧要的细节。我的解决方案是给所有涉及代码读取的命令都加了一个“范围参数”。比如 /代码审查 文件路径AI 只会处理指定文件如果不传参数命令里会明确要求“先列出候选文件让用户确认后再读取”。这个细节极其重要。它把 AI 从“一次性扫描全仓库”的冲动中拉了回来也把 token 消耗控制在一个可接受的范围内。实际操作里我还会用一些固定话术控制输出长度。比如在 /技术方案 里写“如果方案超过 50 行先输出大纲待用户确认后再扩展详细设计”。这可以让 AI 先交付一个精炼版避免一上来输出 2000 行长文占满上下文窗口。命令写得再漂亮如果一次调用就把模型窗口塞满后面就没法聊了。4. 命令包落地排查常见报错与多次翻车后的修复记录4.1 命令不生效按这个顺序排查命令包用得久了多少会遇到“命令怎么不出来了”“敲了命令但是没任何反应”的问题。我整理了一张排查表按顺序走基本都能解决。现象可能原因排查方向与修复方法命令列表里看不到新命令文件位置不对或没被加载确认在 .claude/commands/ 目录下、后缀是 .md、重开会话敲中文命令名时联想不出来终端编码或输入法状态问题切到英文输入法再敲斜杠必要时把文件名改成拼音或英文命令能列出来但执行后像没加载YAML 配置区解析失败检查每行缩进是否用了空格不要用 Tab缩进固定为两空格命令执行了但产物完全不是预期正文里的步骤不清晰或输出模板没写回到六要素检查清单确认约束与输出格式是否写明整个项目里命令没了仓库或目录被移动过确认当前会话的工作目录是否还包含 .claude 目录我把这条排查顺序当成一种肌肉记忆。先看位置再看配置语法再重新加载最后才怀疑提示词本身。很多“命令失效”其实不是命令坏了而是你根本不在那个项目的根目录下工作。4.2 输出质量崩坏阈值设置与上下文管理命令跑起来后最常见的质量问题是“输出太宏大了”。有一次我调用 /技术方案忘了传参数AI 直接输出了模块划分、部署方案、性能优化建议和长达几百行的框架代码片段把整个会话的上下文吃得干干净净后面所有问题都变得短路。排查到最后问题就是命令里缺少长度约束和范围约束。我后来给所有命令都加了“两段式输出”的约定先输出一个压缩版结构用户确认后再展开细节。同时在命令的约束区注明“如果任务涉及的文件超过一个不要一次全部读完先通过搜索定位关键符号再针对性地读取文件片段”。这句话能有效阻止 AI 去把整个项目的源码头尾都读一遍。上下文窗口再大也不是这么浪费的。另外如果某个命令连续输出低质量结果不要去修改一个已经运行很久的会话直接开一个全新会话重新触发命令。新会话没有历史污染命令的提示词也更容易生效。4.3 状态“失忆”和多命令联动问题用命令包装跑全流程时会碰到一个很有迷惑性的问题单独跑一个命令表现都正常但连续跑几个命令之后后面的命令好像忘记前面的输出。比如 /需求分析 输出了功能清单等 /技术方案 跑完再让 /生成测试 分析某个文件AI 居然完全不知道之前的需求边界。这本质上不是命令坏了而是模型在长会话里出现了状态漂移或上下文被截断。解决办法是为命令之间建立一种“握手协议”。我给每个关键命令加了一个固定步骤如果项目中存在工作区状态文件先读取它再开始如果不存在就直接要求用户补充关键上下文。具体做法是让 /需求分析 和 /技术方案 这类命令在输出结束时额外写一份简短的决策记录到 docs/context/ 目录。后续命令启动时第一件事就是读这个文件。这样命令与命令之间就通过一个真实文件接力而不是依赖模型在会话里能记住多少。这个过程很像跨进程通信文件就是共享内存。实测下来加入这个状态文件机制后多命令串联的输出一致性提高了一个档次尤其是涉及多个文件、多次改动的场景AI 前后的口径基本对得上了。5. 把命令包变成团队的长期资产版本化管理与边界意识5.1 命令包随仓库分发与团队基线命令包最大的隐藏收益在于它天然是可以跟着仓库分发的。.claude 目录放在项目根目录下团队成员只要把仓库克隆下来就自动获得这一套工作流。新成员不需要学习“该怎么给 AI 写提示词”只需要知道团队有 10 个命令分别对应什么场景。这就把个人经验变成了一种团队基线。为了让命令包发挥更大作用我还在项目根目录放了一个 CLAUDE.md 文件里面写了团队的代码风格偏好、分支命名规范、测试要求。所有这些规范和命令包一起生效命令负责定义任务流程规范文件负责定义约束条件。两者配合起来AI 的行为模式就比较接近团队中一个熟手同事的水平。5.2 命令的版本管理与演进节奏命令不是写一次就终身不变的它需要持续演进。我强烈建议把命令包的改动当成代码改动来管理。每次想改命令先明确原因是某次执行输出结构不好用还是业务场景变了然后修改文件走一遍和代码一样的评审流程最后合入仓库。这样命令的每一次变化都有记录团队也能看到工作流在进化。实际操作中我还会在命令文件里加一个“最近变更”区记录这个命令改过什么、为什么改。这样一来任何人接手命令包都能理解当前工作流背后的历史原因而不是横空冒出一堆命令。5.3 我的边界经验什么场景不该硬套命令做命令包这件事上了头之后很容易陷入“什么都想封装成命令”的冲动。我后来刻意提醒自己命令适合的是重复度高、流程固定、结果可预期的工作。反过来那些需要大量人为审美判断、需要来回讨论的环节比如产品功能的原型打磨、大规模系统架构的取舍、代码风格的大方向调整并不适合硬套命令。命令提供的是流程框架真正的工程判断还是要靠人。另外不要为了凑数去造命令。如果你在某个环节本来就很顺手不需要 AI 辅助那就不需要一个命令。造一堆低频使用的命令反而会让命令列表变得冗余真正要用的命令被淹没。10 个命令不是目标好用的命令才是目标。最后分享一点个人体会。这套命令包跑了一个多月后我最大的收获反而不是省了多少打字时间而是每个命令都逼着我把工作流拆成“角色、目标、输入、步骤、约束、输出”六个部分。这种结构化的习惯慢慢渗透进了我自己写文档、写方案、甚至提问题的思路里。如果你也在用 Claude Code我不建议一上来就做一套完整命令包先找出自己最痛的那一个环节写一条命令跑两周改成适合你自己的形状。等它真正顺了你自然会想把第二、第三个命令加进去。