1. 为什么我要折腾这套工作流用 Claude Code 写代码这件事最开始我的态度是“能用就行”。终端里敲一句claude丢个需求进去它给我吐代码我复制粘贴到项目里跑一遍能跑通就收工。这种用法持续了大概两个月直到我发现自己每天在做大量重复的“翻译”工作——把脑子里那套中文需求手动翻译成英文提示词再手动补上项目上下文、代码规范、文件路径约束最后还要手动检查它有没有乱改我别的文件。问题不在于 Claude Code 本身不够强而在于我一直在用“聊天”的方式使唤一个“工程工具”。它明明支持自定义命令、支持项目级配置、支持把常用指令固化下来我却每次都在重新发明轮子。后来我花了一个周末把日常最高频的十来个操作全部封装成了中文命令装进了 Claude Code 的 commands 目录里。现在我的工作流是这样的打开终端进项目敲/审查、/补测、/重构、/提交每个命令背后都是一套预设好的提示词模板加约束条件输出直接可用。这套东西我称之为“AI 编程工作流包”核心思路就一句话把重复的提示词工程变成一次性的命令封装。它解决的不是“AI 能不能写代码”的问题而是“怎么让 AI 每次都用同样的标准、同样的格式、同样的边界意识来写代码”的问题。适合谁参考任何已经在用 Claude Code 或者类似 CLI 工具、并且开始觉得“每次都要重新描述需求很烦”的开发者。如果你还在纠结要不要装 Claude Code那这篇可以先收藏等你装好了再回来看。我踩过的第一个坑就是一开始我把所有命令都写成英文想着“反正 AI 看得懂”。结果用了三天就受不了了——我自己看命令列表的时候要反应半天/review和/refactor和/restructure到底哪个是哪个后来全部改成中文/审查、/重构、/整理一眼就知道干什么。命令是给人用的不是给机器用的母语直觉在效率上的优势比想象中大得多。2. 工作流包的整体设计与目录结构2.1 为什么选择命令封装而不是插件Claude Code 的扩展方式有好几种可以写 MCP 服务、可以挂 hooks、也可以用最朴素的 commands 目录。我最终选了 commands理由很实际零依赖、零构建、改完即生效。MCP 服务功能强但要起进程、要配端口、要处理生命周期调试成本高hooks 适合做自动化触发但不适合做“我主动想调用某个能力”的场景。commands 就是一堆 Markdown 文件放在.claude/commands/下面文件名就是命令名文件内容就是提示词模板Claude Code 启动时自动加载。这个选择背后的逻辑是工作流包的核心价值在于提示词质量不在于技术架构。我不需要它多智能我需要它稳定、可预期、改起来方便。Markdown 文件的好处是我随时可以打开一个命令改两句话保存下次调用就生效。没有编译没有重启没有缓存失效问题。对于个人开发者和小团队来说这种“低技术含量但高迭代速度”的方案往往比精心设计的插件系统更实用。目录结构我参考了社区里常见的做法但做了一点调整项目根目录/ └── .claude/ └── commands/ ├── 审查.md ├── 重构.md ├── 补测.md ├── 解释.md ├── 优化.md ├── 提交.md ├── 文档.md ├── 排错.md ├── 设计.md └── 复盘.md十个命令覆盖了我日常开发中最高频的十种操作。每个文件就是一个独立的提示词模板里面用$ARGUMENTS接收调用时传入的参数。比如/审查 src/utils/date.ts$ARGUMENTS就是src/utils/date.ts。2.2 命令设计的三个原则我在设计每个命令的时候遵循了三条原则这三条原则直接决定了命令好不好用。第一条输出格式必须固定。比如/审查命令我要求它必须按“问题等级 | 文件位置 | 问题描述 | 修复建议”四列输出表格不允许自由发挥。为什么因为自由格式的输出我还要花时间读固定格式的输出我可以扫一眼就知道有没有严重问题。AI 的输出不确定性是最大的效率杀手用格式约束把它框住才能变成可流水线处理的东西。第二条边界必须明确。每个命令都要写清楚“只做什么、不做什么”。比如/重构命令里我明确写了“只修改指定文件不得改动其他文件不得改变函数签名不得引入新的外部依赖”。不写这些约束AI 会“热心”地帮你顺手优化一堆别的东西最后 diff 大得没法 review。第三条上下文必须自包含。命令里要包含足够的项目背景信息不能假设 AI 记得之前的对话。比如/补测命令里我会让它先读package.json确认测试框架再读目标文件确认导出结构最后才生成测试。这样即使在一个全新会话里调用它也能产出符合项目规范的代码。2.3 命令清单与适用场景对照下面这张表是我实际在用的十个命令以及它们各自解决什么问题。你可以根据自己的技术栈和习惯调整但建议先照搬跑通再按需修改。命令核心作用典型调用方式输出形态/审查代码质量与安全审查/审查 src/api/问题表格 修复建议/重构结构优化不改行为/重构 src/utils/date.ts重构后代码 变更说明/补测生成单元测试/补测 src/utils/date.ts测试文件 覆盖率说明/解释逐段讲解代码逻辑/解释 src/core/engine.ts分段注释 流程图文字版/优化性能与可读性优化/优化 src/render/list.ts优化后代码 对比说明/提交生成规范提交信息/提交commit message 变更摘要/文档生成 API 文档/文档 src/api/user.tsMarkdown 文档/排错根据报错定位问题/排错 TypeError: xxx原因分析 修复步骤/设计根据需求出方案/设计 用户权限模块方案对比 推荐选型/复盘总结本次改动/复盘改动清单 风险提示这张表建议放在项目 README 或者团队 wiki 里新成员进来一看就知道有哪些“快捷指令”可用。我团队里有个后端同事之前对 AI 编程一直持怀疑态度觉得“生成的代码不可控”。后来我把/审查和/补测两个命令推给他他用了一周之后跟我说现在他写完一个模块第一件事就是跑/审查比他自己逐行检查快得多而且经常能发现他忽略的边界情况。3. 核心命令的提示词拆解与实操要点3.1/审查命令把代码审查变成流水线/审查是我用得最频繁的命令没有之一。它的提示词模板大概是这样的结构你是一名资深代码审查员。请审查 $ARGUMENTS 路径下的代码。 审查维度 1. 安全性注入风险、敏感信息泄露、权限校验缺失 2. 健壮性空值处理、边界条件、异常捕获 3. 可维护性命名规范、函数长度、重复代码 4. 性能不必要的循环、重复计算、内存泄漏风险 输出格式必须严格遵守 | 等级 | 文件:行号 | 问题描述 | 修复建议 | |------|----------|---------|---------| | 高/中/低 | ... | ... | ... | 约束 - 只报告真实存在的问题不要为了凑数编造 - 每条建议必须可操作不要写“建议优化”这种空话 - 如果某个维度没有问题写“未发现明显问题”这个模板里最关键的是输出格式约束和**“不要凑数”**那条。我试过不加“不要凑数”结果它给我列了二十条“建议添加注释”“建议统一命名风格”这种废话真正的高危问题反而被淹没了。加上约束之后输出通常只有三到八条但每条都值得看。实操中还有一个技巧审查范围要具体到文件或目录不要整个项目。我试过/审查 src/结果它读了太多文件输出质量明显下降而且速度很慢。后来改成/审查 src/api/user.ts这种粒度效果最好。如果确实要审查整个模块我会分几次调用每次一个子目录。注意/审查命令不会自动修改代码它只输出报告。修复需要你手动做或者再调用/重构让它改。这个设计是故意的——审查和修改分开避免它“边审边改”导致 diff 混乱。3.2/重构命令约束比能力更重要/重构的提示词里约束条件占了将近一半篇幅。因为重构这件事AI 太容易“用力过猛”了。你让它重构一个函数它可能把整个文件的导出结构都改了最后调用方全挂。我的模板核心约束如下请重构 $ARGUMENTS要求 必须遵守 - 只修改指定文件不得改动其他任何文件 - 不得改变任何导出函数/类的名称和签名 - 不得引入新的外部依赖 - 不得改变现有测试的预期行为 重构目标按优先级 1. 消除重复代码 2. 降低函数复杂度单个函数不超过 40 行 3. 改善命名可读性 4. 提取可复用逻辑 输出 1. 重构后的完整文件内容 2. 变更说明表格| 变更点 | 原实现 | 新实现 | 理由 |这里有个细节“不得改变现有测试的预期行为”这条约束是我踩坑之后加的。有一次我让它重构一个工具函数它把返回值从null改成了undefined逻辑上更“干净”了但下游有个地方用 null判断直接出 bug。从那以后凡是涉及行为边界的改动我都在命令里明确禁止。另一个实操心得重构前先跑一遍测试重构后再跑一遍。命令本身不负责跑测试但你的工作流里应该有这一步。我通常的节奏是/审查发现问题/重构修复然后手动npm test确认最后/提交生成 commit message。3.3/补测命令让测试生成真正可用/补测的难点在于AI 生成的测试经常是“为了覆盖率而测试”——测了一堆 getter/setter真正的边界条件一个没覆盖。我的解法是在提示词里强制它先分析再生成请为 $ARGUMENTS 生成单元测试。 第一步先读取文件列出所有导出成员及其签名。 第二步分析每个成员的分支逻辑列出需要覆盖的场景 - 正常路径 - 边界值空、零、最大值、最小值 - 异常路径抛错、返回错误码 第三步根据项目现有测试框架生成测试代码。 约束 - 测试框架和断言风格必须与项目现有测试一致 - 每个测试用例必须有明确的断言不允许只调用不断言 - 边界条件测试必须占总数的一半以上 - 不要测试私有函数只测导出接口“边界条件测试必须占一半以上”这条是我反复调整后定下来的比例。之前不设比例生成的测试里百分之八十都是正常路径覆盖率数字好看但实际保护力很弱。设了比例之后它会认真去翻代码里的if分支和try/catch产出的测试质量明显提升。还有一个坑如果项目没有测试框架/补测会自己选一个。这时候最好在命令里指定比如“使用 Vitest”或“使用 Jest”。我一般会在项目根目录放一个.claude/commands/补测.md的变体针对不同项目写死框架避免它每次选的不一样。3.4/排错命令从报错到修复的快速通道/排错的使用场景很直接终端里报了个错复制错误信息敲/排错 TypeError: Cannot read property map of undefined它去代码里找原因。这个命令的提示词设计要点是要求它先定位再修复项目报错如下 $ARGUMENTS 请按以下步骤处理 1. 在代码库中搜索相关文件和行号 2. 分析根本原因不要只修表面症状 3. 给出修复方案优先选择改动最小的方案 4. 如果涉及多个文件列出所有需要改动的文件 输出格式 - 根本原因... - 涉及文件... - 修复步骤1. 2. 3. - 验证方式...“优先选择改动最小的方案”这条很重要。AI 有时候会给你一个“架构级”的修复方案比如“建议引入状态管理库来解决这个问题”而实际上你只需要加一个空值判断。加上这条约束后它会先给最小改动方案如果你觉得不够再让它给备选方案。提示/排错对错误信息的完整性有要求。如果只给一句“报错了”它很难定位。最好把完整的堆栈信息、复现步骤、相关代码片段一起传进去。我通常的做法是终端里选中错误信息直接粘贴到命令后面。4. 安装配置与工作流落地实录4.1 从零开始把命令装进去假设你已经装好了 Claude Code终端里敲claude能正常启动。接下来就是创建命令目录。在项目根目录下执行mkdir -p .claude/commands然后把十个 Markdown 文件放进去。你可以手动创建也可以写个脚本批量生成。我一开始是手动建的后来发现每次新项目都要重复一遍就写了个初始化脚本#!/bin/bash # init-claude-commands.sh COMMANDS_DIR.claude/commands mkdir -p $COMMANDS_DIR cat $COMMANDS_DIR/审查.md EOF 你是一名资深代码审查员。请审查 $ARGUMENTS 路径下的代码。 ...完整提示词 EOF # 其余命令类似 echo 已安装 10 个中文命令到 $COMMANDS_DIR这个脚本我放在 dotfiles 仓库里新项目 clone 下来跑一次就行。如果你团队里多个人用建议把.claude/commands/提交到 git这样所有人共享同一套命令输出标准也统一。配置完成后在 Claude Code 里敲/应该能看到命令列表。如果没看到检查两个地方一是目录路径对不对必须是项目根目录下的.claude/commands/二是文件扩展名必须是.md不能是.txt或没有扩展名。4.2 命令之间的串联工作流单个命令好用但真正的效率提升来自命令串联。我日常最常用的一个完整工作流是这样的写完一个新模块先跑/审查 src/new-module/看有没有高危问题如果有问题跑/重构 src/new-module/file.ts修复跑/补测 src/new-module/file.ts生成测试手动跑测试确认通过跑/提交生成 commit message跑/复盘总结这次改动这一套下来原本需要半小时的收尾工作压缩到十分钟以内。而且因为每个环节的输出格式固定我基本不用动脑子去“理解”AI 说了什么扫一眼就知道下一步该干什么。还有一个进阶用法把多个命令写进一个 shell 脚本。比如#!/bin/bash # review-and-test.sh TARGET$1 claude /审查 $TARGET claude /补测 $TARGET这样一条命令就能跑完审查和补测。不过要注意Claude Code 的每次调用是独立的上下文不共享所以/补测不会知道/审查发现了什么问题。如果你需要上下文传递得手动把审查结果作为参数传给下一个命令。4.3 团队协作中的落地经验我一个人用这套东西用了两周之后推给了团队里另外三个人。落地过程中遇到的最大阻力不是技术问题而是习惯问题。大家习惯了“有问题直接问 AI”突然要改成“先想清楚用哪个命令”一开始很不适应。我的解法是先推一个命令用出效果再推下一个。我选的是/审查因为它的价值最直观——跑一次出一张问题表谁都能看懂。用了三天之后有人开始主动问“还有没有别的命令”。这时候再把/补测和/提交推出去接受度就高多了。另一个经验是命令的提示词要允许个人微调。我团队里有个同事对代码风格特别在意他把/重构命令里的“函数不超过 40 行”改成了“不超过 25 行”还加了一条“优先使用早返回”。这些个人偏好没必要统一每个人维护自己的命令变体就行。共享的是工作流框架不是每个细节。5. 常见问题与排查技巧实录5.1 命令不生效或找不到这是最高频的问题通常有三个原因。第一是目录位置不对.claude/commands/必须在项目根目录不能在子目录里。第二是文件编码问题Markdown 文件必须是 UTF-8如果用了 GBK 编码中文命令名会乱码。第三是 Claude Code 版本太旧早期版本对自定义命令的支持不完整建议升级到最新版。排查方法很简单在 Claude Code 里敲/help看输出里有没有列出你的命令。如果没有就是加载失败。这时候检查文件路径和编码基本能解决。5.2 命令输出格式不稳定有时候你明明在提示词里写了“必须按表格输出”它还是给你一段散文。这种情况通常是因为提示词里的约束不够靠前。AI 对提示词开头和结尾的内容更敏感中间部分容易被忽略。我的做法是把格式约束放在提示词的最前面用“必须”“严禁”这种强约束词并且在结尾再重复一遍。另一个技巧是给一个输出示例。比如在/审查命令里加一行输出示例 | 等级 | 文件:行号 | 问题描述 | 修复建议 | |------|----------|---------|---------| | 高 | src/api/user.ts:42 | 未校验用户输入 | 添加 zod schema 校验 |有了示例之后格式稳定性明显提升。5.3 命令执行太慢或读太多文件/审查和/解释这类命令需要读文件如果目标路径太大会非常慢。我的经验是单次调用涉及的文件不超过五个。如果确实要审查一个大模块分多次调用每次一个子目录。还有一个隐藏问题Claude Code 可能会读node_modules或构建产物。这会让它卡很久。解决方法是在项目根目录放一个.claudeignore文件把不需要读的目录排除掉node_modules/ dist/ build/ *.min.js这个文件的作用类似.gitignore但只影响 Claude Code 的文件读取范围。5.4 命令修改后不生效改了命令文件的内容但下次调用还是旧的行为。这通常是因为 Claude Code 有缓存机制。解决方法很简单退出当前会话重新启动claude。如果还不行检查是不是改错了文件——有时候项目里有两个.claude目录一个在根目录一个在用户主目录命令加载优先级不同。注意用户主目录下的~/.claude/commands/是全局命令对所有项目生效项目根目录下的.claude/commands/是项目级命令只对当前项目生效。如果同名项目级会覆盖全局级。我一般把通用命令放全局项目特有的放项目级。5.5 常见问题速查表现象可能原因解决方法命令列表里没有自定义命令目录位置错误或编码问题确认.claude/commands/在项目根目录文件为 UTF-8输出格式不符合预期约束不够强或位置靠后格式要求放开头加示例结尾重复执行很慢读取文件过多缩小目标路径配置.claudeignore修改命令后行为不变缓存未刷新重启 Claude Code 会话命令名乱码文件编码非 UTF-8转码为 UTF-8命令执行报权限错误文件权限不足chmod 644命令文件6. 命令包的扩展与个人化调整6.1 根据技术栈定制命令我这十个命令是围绕 TypeScript 和 Node.js 项目设计的如果你用的是 Python 或 Go提示词里的框架和工具需要替换。比如/补测命令里TypeScript 项目写的是“使用 Vitest”Python 项目要改成“使用 pytest”Go 项目要改成“使用标准库 testing”。替换的时候注意一个原则只改工具名和框架名不改命令结构。命令结构是经过验证的改了容易出问题。比如/审查的四维审查框架安全、健壮、可维护、性能换成任何语言都适用不需要动。6.2 增加项目特有的命令十个命令是通用底座实际项目中你可能会需要一些特有的命令。比如我最近在一个前端项目里加了一个/组件命令专门用来生成符合项目组件规范的 React 组件模板。提示词里写死了项目的目录结构、样式方案、状态管理方式生成出来的组件直接能用不需要手动调整。加命令的方法很简单在.claude/commands/下新建一个.md文件写好提示词重启会话即可。建议新命令先在个人项目里跑一周稳定了再推到团队共享目录。6.3 命令的版本管理命令文件建议纳入 git 管理但要注意一点不同分支可能需要不同的命令版本。比如你在开发一个实验性功能可能需要一个/实验命令来生成实验代码合并到主分支后这个命令就不需要了。我的做法是主分支只保留通用命令实验性命令放在个人分支或者本地不提交。另外命令的修改历史最好有记录。我习惯在命令文件顶部加一行注释!-- 最后修改2025-01-15调整了输出格式约束 --这样出问题的时候能快速定位是哪次改动导致的。7. 我实际用下来的几点体会这套工作流包我用了大概三个月最大的感受是AI 编程的效率瓶颈不在模型能力而在交互方式。同样的模型你用聊天的方式使唤它和用命令的方式使唤它产出质量差很多。命令封装本质上是在做“提示词的工程化”——把一次性的、随意的对话变成可重复、可迭代、可共享的工程资产。另一个体会是约束比能力更重要。我花在写约束条件上的时间比花在写“让它做什么”上的时间多得多。但正是这些约束让输出变得可预期。没有约束的 AI 像个聪明但没规矩的实习生有约束的 AI 才像个靠谱的同事。最后一个建议从三个命令开始不要一上来就搞十个。我一开始装了十个结果有一半用不上反而增加了选择负担。后来精简到/审查、/补测、/提交三个高频命令用顺了之后再逐步加。工作流这东西少即是多能坚持用下去的才是好工作流。