拓冰网站定制 
Claude Code 折腾了一阵子我一直觉得这工具好用是好用但每次输入命令都得憋英文还要在脑子里过一遍 Prompt 模板有点累。后来干脆花了两个周末把日常最常用的操作全部封装成了带中文提示的 Slash Command一共 10 个做成了一个可以直接拷到项目里用的工作流包。这文章不是讲概念就是把这 10 个命令的设计思路、配置文件写法、踩过的坑完整摊开给同样在用 Claude Code 写代码、做 Code Review、理项目的人一个能直接抄作业的参考。先说清楚这套东西解决什么问题很多人把 Claude Code 当成一个高级聊天框来用问一句答一句完全没有发挥出它真正的优势。它其实支持自定义命令可以把复杂的 Prompt、固定的处理流程、甚至本地脚本全部打包成一个短命令输入/修复就能触发一整套 Bug 分析流程而不是每次手动敲一大段话。10 个中文命令做完后我的日常协作流程变成了三步写完代码敲/审查开会前敲/周报接手老项目敲/导读。效率提升是实打实的更关键的是这套做法让没有提示词经验的同事也能轻松上手。1. 整体设计为什么要把命令做成中文 Slash 命令1.1 Claude Code 的原生命令机制这一节先介绍背景知识用过的朋友可以跳过。Claude Code 支持自定义 Slash Command命令文件放在项目根目录的.claude/commands/下每个命令由markdown提示词文件和可选的TypeScript脚本文件组成。你在对话框输入/某某时Claude Code 会自动读取对应的 Markdown 内容把其中的参数替换成你实际输入的值然后作为系统提示词的一部分发给大模型。这套机制比我一开始以为的“预置 Prompt 模板”要强得多。Markdown 文件只是静态文本真正让它活起来的是旁边的.ts脚本文件。脚本可以读取当前项目的文件状态、Git 暂存区内容、甚至执行终端命令把结果拼接到提示词里再发给模型。这意味着我可以在命令里写“请分析以下 Git Diff”然后脚本自动把git diff --cached的输出塞进去。原生机制里还有几个细节值得注意。命令文件区分全局和项目级全局命令放在~/.claude/commands/所有项目可用项目级放在项目根目录适合和团队共享。命令参数通过$ARGUMENTS传递文件名中的数字会作为参数编号。这些细节在后面配置时会反复用到。1.2 选择中文命名的三个决定性理由第一个理由是团队协作门槛。我们小组六个人真正写过 Prompt 的不到一半大部分同事对 AI 工具的态度是“能用但不想折腾”。如果我给他们分享的是一堆英文 Prompt 模板基本等于没分享。但如果是/审查、/周报这样的中文命令只要看一眼列表就能猜到功能用一次就能记住。这个差别在团队落地时是决定性的。第二个理由是记忆成本。我知道很多人觉得英文命令更“正统”但作为一天要敲几十次命令的人来说记忆负荷是真实存在的。尤其在上下文切换频繁的时候脑子里要同时装业务逻辑和命令语法很容易卡壳。中文命令天然符合我的思维习惯。更重要的是Claude Code 的模型本身对中文理解力很强命令名用什么语言对它来说没有区别但这降低了我的工作记忆负担。第三个理由是语义完整性。英文 Slash Command 往往受限于单词长度比如/review、/fix、/log这些缩写能表达功能但不表达场景。中文命令可以用“审查代码”“梳理日志”“生成周报”这样的动宾结构信息密度更高。当一个命令包含多个操作步骤时中文命名能把整个流程的目的直接表达出来这比一个含糊的英文单词要清楚得多。1.3 十个命令的全景地图我最终保留了 10 个命令按照使用频率和场景分成四类。先给你一张全景表后面每一类再展开讲。命令名称触发方式核心功能适用场景代码审查/审查 [范围]检查本地修改或指定文件输出代码问题清单提交前自检、MR 前预审缺陷定位/定位 [现象]根据错误信息或现象描述定位代码中可能的问题点线上 Bug 排查、报错处理提交信息/提交 [描述]生成符合 Conventional Commits 规范的提交说明Git 提交前提交记录/历史 [范围]分析 Git 提交历史输出提交规律与问题总结版本回顾、绩效总结差异解读/变更 [文件]解释工作区与暂存区的代码改动意图Code Review 辅助重构规划/重构 [目标]输出重构方案包含步骤拆解、风险影响、验证方案技术债清理文档生成/文档 [模块]为目标代码模块生成 README 与接口说明新模块交付、交接项目导读/导读通读项目结构输出架构说明与新手指南新人接手、快速上手周报助手/周报分析本周提交记录生成工作总结周报撰写学习助手/教学 [主题]解释项目中的特定技术概念附带项目内实例技术学习、新人培训这张表里前四个是高频使用的“主力命令”几乎每天都会碰中间三个是“低频高价值命令”虽然用得少但每次都能省半小时以上最后三个是“团队协作命令”主要给非核心开发人员用。2. 核心实现三个高频命令的逐行拆解2.1 代码审查命令的完整实现代码审查命令是我最早实现的一个也是迭代次数最多的。它的核心思路是让 Claude Code 扮演资深 Reviewer 的角色对指定范围的代码进行审查输出问题清单而非泛泛而谈。先看目录结构这是标准做法.claude/commands/ ├── 审查.md ├── 审查.ts ├── 定位.md ├── 定位.ts └── ...审查.md的内容如下你是一名拥有 15 年经验的资深代码审查专家擅长发现潜在 Bug、安全隐患和性能瓶颈。 请审查以下范围内的代码变更重点关注 1. 逻辑错误与边界条件空值、并发、溢出等 2. 安全隐患注入、敏感信息泄露、越权访问 3. 性能问题不必要的大对象创建、循环内查询、N1 问题 4. 代码风格与可维护性命名、重复代码、魔法数字 5. API 设计的合理性参数校验、返回值定义 输出格式 - 按严重程度分为【阻断级】【建议级】【优化级】 - 每个问题需要给出文件路径、行号如可定位、问题描述、修改建议 - 如果审查范围内没有问题请明确说明不要为了凑数而输出无意义建议 审查范围$ARGUMENTS这里的核心是$ARGUMENTS变量。用户在输入/审查 全部时这个变量会被替换成“全部”输入/审查 src/utils.ts时会被替换成文件路径。但标记文件里不能执行任何代码真正去拉取 Git Diff 的工作要由 TypeScript 脚本来做。审查.ts的核心逻辑如下import * as cp from child_process; import * as fs from fs; import * as path from path; function getGitDiff(scope: string): string { // git diff 是核心数据源只审查未提交的改动 const args scope 全部 ? [diff, --cached] : [diff, --cached, --, scope]; const output cp.execSync(git ${args.join( )}, { encoding: utf-8, maxBuffer: 10 * 1024 * 1024 // 大项目 diff 很容易超默认 buffer }); return output; } function truncate(text: string, maxLen: number 12000): string { // 超过上下文窗口的直接舍弃中间部分保留开头和结尾 if (text.length maxLen) return text; const half Math.floor(maxLen / 2); return text.slice(0, half) \n\n...[中间内容已省略]...\n\n text.slice(-half); } export async function main(args: string[]): Promisestring { const scope args.join( ) || 全部; // 也要包含暂存区状态以外的上下文信息 const branch cp.execSync(git branch --show-current, { encoding: utf-8 }).trim(); const lastCommit cp.execSync(git log -1 --oneline, { encoding: utf-8 }).trim(); const diff getGitDiff(scope); return 当前分支${branch} 最近提交${lastCommit} 审查范围${scope} ${truncate(diff)}; }这个脚本做的事情非常简单把 Git Diff 抓取出来加上当前分支名和最近提交信息一并交给 Claude。关键点在于truncate函数这是我在实践中发现的硬性需求。没有它时遇到大型项目的一次提交动辄几万字符的 DiffClaude 的上下文窗口会被大量无关代码刷屏导致真正重要的逻辑反而不被关注。截断后虽然丢失了中间细节但模型能集中精力处理改动上下文的关键部分效果反而更稳定。还有个细节我要特别提示git diff --cached只审查暂存区的改动不审查工作区未暂存的部分。这种设计是有意的因为暂存区内容往往是提交意图较明确的代码。但我后来发现很多人用命令时不习惯先git add所以我在审查.ts里做了逻辑调整如果暂存区为空就自动改为对比工作区和 HEAD。这个适应性逻辑极大减少了误操作率。2.2 缺陷定位命令把问题描述转换为代码路径缺陷定位命令解决的是最让人头疼的排查环节线上报了一个错错误信息很抽象只知道大概发生在哪个模块但要找到具体代码位置往往要翻半天日志。这条命令的设计思路是“现象输入路径输出”。定位.md的内容你是一个资深 Debug 专家。根据用户描述的错误现象结合项目代码结构进行以下分析 1. 根据异常信息的关键词推测可能出错的函数调用链路 2. 在项目代码中搜索与错误相关的函数、变量、异常类 3. 根据调用关系判断最可能的出错位置 4. 给出 2-3 个可疑点每个可疑点包含文件路径、函数名、行号如可定位、出错概率、排查建议 注意 - 如果错误信息中包含堆栈片段优先从堆栈线索入手 - 不要给无关的全局建议一定要定位到具体文件和函数 - 如果无法定位列出你搜索过哪些关键词和文件帮助用户进一步提供信息 错误现象$ARGUMENTS定位.ts的实现逻辑就更复杂一些因为要主动搜索代码内容import * as cp from child_process; import * as fs from fs; import * as path from path; const IGNORE_DIRS [node_modules, dist, build, .git, vendor, __pycache__]; function searchInFiles(needle: string): string[] { // 这里有两个搜索策略文件名匹配 和 内容匹配 const results: string[] []; const needleLower needle.toLowerCase(); // 策略一在文件内容里搜关键词用 ripgrep 效率高很多 try { const rgOutput cp.execSync(rg -l -i ${needle} --type-add web:*.{ts,tsx,js,jsx,vue,py,java,go} -t web . 2/dev/null | head -30, { encoding: utf-8, maxBuffer: 5 * 1024 * 1024 }); results.push(...rgOutput.trim().split(\n).filter(Boolean)); } catch { // ripgrep 没装或没有匹配都会走到这里 } // 策略二按文件名匹配 const files walkSync(./src, 4); // 限制深度避免遍历整个 node_modules for (const file of files) { const base path.basename(file); if (base.includes(needle) || needleLower.includes(base.replace(/\.[^.]$/, ).toLowerCase())) { results.push(file); } } return [...new Set(results)]; } function walkSync(dir: string, maxDepth: number): string[] { // 一个简单的递归遍历函数再加个深度限制防止爆掉 if (maxDepth 0) return []; const files: string[] []; if (!fs.existsSync(dir)) return files; for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { const full path.join(dir, entry.name); if (IGNORE_DIRS.includes(entry.name)) continue; if (entry.isDirectory()) { files.push(...walkSync(full, maxDepth - 1)); } else if (entry.isFile()) { files.push(full); } } return files; } export async function main(args: string[]): Promisestring { const description args.join( ) || 未提供错误现象; const searchTerms description .split(/\s/) .filter(term term.length 1) .slice(0, 5); // 最多取5个关键词不然搜索范围太大 const foundedFiles: string[] []; for (const term of searchTerms) { foundedFiles.push(...searchInFiles(term)); } const uniqueFiles [...new Set(foundedFiles)].slice(0, 30); // 读几个候选文件的头部给模型一些结构线索 const fileSnapshots uniqueFiles.slice(0, 5).map(file { try { const content fs.readFileSync(file, utf-8).slice(0, 1500); return ### ${file}\n${content}; } catch { return ; } }).join(\n\n); return 错误现象${description} 在项目中找到以下可能相关的文件 ${uniqueFiles.length 0 ? uniqueFiles.join(\n) : 未找到匹配文件请检查关键词或扩大搜索范围。} 其中部分文件的内容预览如下 ${fileSnapshots || 无可用预览} ; }这里我用了一个组合搜索策略先用ripgrep搜内容匹配再用路径遍历做文件名匹配。为什么要两套方案因为错误信息里的关键词经常不是文件名而是异常类名、接口名、或者中文字段名。rg搜内容能覆盖这类情况但不一定每个环境都装了 ripgrep而且大目录全量搜索很慢。文件名的匹配虽然覆盖率低但执行速度快两者互补。另外一个值得一提的取舍是walkSync的深度限制。如果项目采用平铺结构深度 1-2 就能找到如果项目嵌套深4 层是合理上限。再深基本都是业务代码的分包目录对定位帮助不大还会因遍历过慢影响命令响应速度。这些细节看着琐碎实际用起来区别很大。2.3 提交信息命令让 Git 提交从憋文案变成填空这条命令做的是最基础但最烦人的事。很多人提交代码时提交信息随便写个fix bug或update团队看历史记录时一头雾水。这条命令用 Claude 理解 Diff 内容自动生成规范提交信息。提交.md根据代码变更内容生成符合 Conventional Commits 规范的提交信息。 要求 1. type 限用feat / fix / refactor / docs / chore / perf / test 这七种 2. 简要描述中英文混合中文为主体动词开头不超过 20 个汉字 3. 在提交信息中说明修改的核心文件和影响函数 4. 如果有破坏性变更需要在正文中用 BREAKING CHANGE: 标记 5. 最终输出只保留提交信息原文不要增加任何解释你的思路的内容 变更描述如为空则自动分析 $ARGUMENTS提交.ts的主要逻辑import * as cp from child_process; export async function main(args: string[]): Promisestring { const userDescription args.join( ); // 这里做的是增强版 diff 摘要比把完整 diff 直接扔给模型效果更好 let diff ; try { diff cp.execSync(git diff HEAD --stat, { encoding: utf-8 }).trim(); // 加上实际文件变更比率的参数据让模型更好判断本次修改的规模 const diffSummary cp.execSync(git diff HEAD --dirstatfiles,0, { encoding: utf-8 }).trim(); diff \n\n目录变更统计:\n diffSummary; } catch { diff 无 Git 信息; } return 用户描述${userDescription || 未提供请直接从 Diff 中分析} ## 本次变更统计 ${diff} ## 请基于以上信息生成提交信息。; }这里没有把整个 Diff 交给模型只给了--stat的统计即文件和行数变化。这么做省 token 而且效果不差。模型根据文件变更列表加上用户的一句话描述已经足够产出合理的提交类型判断。把整个 Diff 塞进去反而会产生噪音比如模型会盯着某些具体实现细节反而忽视了整体变更意图。产出提交信息后用户可以直接复制使用也可以跟我给的模板对比调整。这个命令看着简单但它的实际效果非常稳定因为提交信息生成是一个极度适合 LLM 的任务——不需要深度推理只需要概括归纳。3. 配置与安装从零搭建完整的命令工作流包3.1 配置文件目录结构与全局命令安装这套工作流包的核心文件全部放在.claude/commands/下。如果只是想自己用可以放到全局目录~/.claude/commands/这样所有项目都能共用。如果是要给团队共享建议提交到仓库里放在项目根目录下配合团队的.claude/settings.json配置文件一起使用。团队的共享场景里还要注意一点很多人会直接在项目里修改.claude下的文件导致团队命令版本不一致。我建议命令文件尽量放在独立的私有目录维护通过构建脚本部署到项目里或者直接以文件方式共享让每个人自己安装。这个选择虽然多了一步操作但避免了“我在你机器上改了命令你机器上是旧的而且完全不知道差异在哪”的尴尬局面。配置文件这块一个常见需求是设置命令权限。Claude Code 默认在执行脚本类命令时会弹出确认框有些团队希望静默执行。这时可以在.claude/settings.json中配置权限{ permissions: { allow: [ Bash(git diff:*), Bash(git log:*), Bash(rg:*), Read(*) ], deny: [ Bash(git push:*), Bash(git reset:*), Bash(rm:*) ] } }这个配置的意思是允许读取文件、查看 Git Diff 和日志、搜索代码禁止推送、硬重置和删除操作。我强烈建议任何团队都做一层这样的限制因为 Claude Code 为了完成“分析任务”可能需要读文件但完全没有理由执行推送或删除命令。权限配置不花一分钟但能挡住很多误操作。3.2 命令的运行机制Markdown 与 TypeScript 的分工边界这是理解 Claude Code 的自定义命令最核心的一点md文件与ts文件的职责边界。我从多次迭代中总结的经验是Markdown 文件的职责是定义模型的角色、任务和约束。它所有的文字都会传给 Claude作为系统提示词的一部分。要注意的是这个文件里不能直接执行任何命令它的作用是告诉模型要做什么。TypeScript 文件的职责是提供数据、执行系统操作。它会在 Claude 开始处理之前执行产生的返回值会作为一个特殊消息注入到上下文中。主函数通常接受args(string[])作为参数这个参数就是用户在命令后输入的内容。两者之间的配合逻辑是这样的在/审查命令里审查.md描述代码审查专家的行为和输出格式而审查.ts抓取 Git Diff 的实际数据把数据加进上下文中。模型拿到数据和任务指令后输出最终的审查结果。没有.ts文件的命令也可以正常运行$ARGUMENTS会被用户输入替换但无法动态抓取项目状态。关于 TypeScript 文件的几个实操要点ts文件的入口函数必须是main(args: string[]): Promisestring返回值会被拼接到上下文中。ts文件通过 Node.js 执行所有 Node 内置模块都能直接用。文件内不要写 console.log输出结果应通过返回值传递。命令执行环境是项目根目录所以相对路径不会出错。脚本异常时命令会失败但不会中断 Claude Code 主进程。这些约定最初我花了不少时间摸索因为官方文档并不会明确告诉你返回值如何连接提示词。实践中试错几轮后我总结成上面这几条基本涵盖了 90% 的场景。3.3 与 Visual Studio Code 的联动配置我在日常开发中用 Visual Studio Code 自带的终端来跑 Claude Code这个组合体验不错。关键要在 VS Code 的集成终端里允许 Claude Code 使用快捷命令以及配置好终端会话的保持。具体的配置方式是在 VS Code 的settings.json里设置{ terminal.integrated.env.windows: { CLAUDE_CODE_OPTS: --dangerously-skip-permissions } }注意这里--dangerously-skip-permissions是跳过权限确认适合个人开发环境使用。如果团队协作建议不要开这个选项而是在settings.json里精确配置允许列表前面说的权限配置就是这个用途。另外我习惯把 Claude Code 单独放到一个终端标签页并给它设置一个独立的配色避免跟其他终端输出混在一起。VS Code 的终端界面支持多标签在terminal.integrated.tabs里可以把 Claude Code 的会话固定住这样随时敲命令都不用找。3.4 一个完整的命令部署流程示例假设你要把整套工作流包部署到一个新成员电脑上最稳妥的手动流程是这样的先安装 Claude Codenpm install -g anthropic-ai/claude-code克隆项目到本地执行claude初始化复制命令目录把.claude/commands/整个文件夹放到项目根目录注意不要覆盖别人已经改过的配置检查settings.json权限配置确保Bash(git diff:*)等允许规则在里面在项目目录运行claude输入/查看命令列表是否出现中文命令先跑一遍/文档 当前目录做一个冒烟测试确认 TypeScript 脚本能正常执行这个流程我已经给组里新人走过三轮基本上没有盲点。4. 实操过程与核心环节实现4.1 一次完整的代码审查实战记录为了让你对这套工作流包有更直观的感受我记录一次真实的/审查操作过程。那天的场景是一个变更涉及用户登录模块修改了验证码校验逻辑和 Token 刷新机制。我在终端输入/审查命令执行后终端会把审查.ts抓取到的 Git Diff 与审查.md的命令文本合并作为上下文模型开始分析。大约 10 秒后输出了一份报告其中有一条我印象很深【阻断级】verifyCode.ts第 89 行验证码校验失败时直接抛出异常导致整个登录请求回滚但在验证码校验之前已经被查询的验证码记录、尝试次数等信息处于未清理状态极端并发场景下可能导致验证码记录泄漏。这条我确实没想到。原代码里验证码校验失败就立刻抛出业务异常框架层会做事务回滚但那张记录验证码的表因为事务隔离级别的问题在特定数据库配置下并不会完全回滚。这种场景靠人肉一眼看出很难但 LLM 结合了代码上下文之后真的能找到这种跨模块的隐蔽问题。模型还正确识别了一个潜在安全风险——在重置 Token 之前没有校验旧 Token 是否已经过期给重放攻击留了窗口。这两条建议都直接提进了 MR 里同事看到后立刻调整了逻辑。自从团队开始用/审查大家可以明显感受到提交前的隐患变少了。4.2 缺陷定位命令的高效排查实例有一次后台报了个杂音错误日志里反复出现JSON parse error: Unexpected token但是没有明确堆栈。我直接敲了/定位 JSON parse error 日志上传。命令脚本把这三个关键词并行搜索了一遍。结果性能非常明显因为我的日志上传模块里有一段手写的 JSON 序列化逻辑它拼 SQL 的时候不小心在字符串数组里留下了尾逗号PHP 那边解析到数组最后一个位置时直接挂了。如果没有这套命令靠手动打开项目反复搜索关键词至少要到 5-10 分钟甚至更久。一个命令下去3 秒就列出 6 个可疑文件我打开第一个就找到了问题。这里有个使用场景要提示命令的效果跟错误描述的信息量强相关。如果只知道报错了模型也只能瞎猜。我总结了一句口诀报错信息要给出【异常类型 关键词 大概功能模块】准确率翻倍。比如上面的JSON parse error 日志上传就包含了这三类信息。4.3 周报助手命令的团队落地效果这个命令是我意料之外好评最多的一个。起因是我发现每个周五写周报都要打开 Git 记录整理提交信息步骤繁杂。后来我写了/周报命令脚本自动统计当前用户本周的提交记录按日期分组输出每个提交的标题、影响文件、关联的 MR 号。模型再将这些内容整理成周报格式。周报.ts的核心逻辑import * as cp from child_process; export async function main(args: string[]): Promisestring { // 默认统计本周一到今天 const monday new Date(); const day monday.getDay(); const diff day 0 ? 6 : day - 1; monday.setDate(monday.getDate() - diff); monday.setHours(0, 0, 0, 0); const since args[0] || monday.toISOString().slice(0, 10); // git log 按作者 时间过滤 const author cp.execSync(git config user.name, { encoding: utf-8 }).trim(); const log cp.execSync( git log --author${author} --since${since} 00:00:00 --untilnow --prettyformat:%h %ad %s --dateformat:%Y-%m-%d %H:%M, { encoding: utf-8, maxBuffer: 10 * 1024 * 1024 } ).trim(); // 统计每个文件的变更行数, 给周报提供更具体的数据 const stat cp.execSync( git log --author${author} --since${since} 00:00:00 --numstat --prettyformat:%h | awk /^[0-9]/ {added$1; deleted$2} END {print added, deleted}, { encoding: utf-8, maxBuffer: 5 * 1024 * 1024 } ).trim(); return 本周起始日期${since} 提交记录 ${log} 变更统计新增行数 删除行数${stat} 请把以上内容整理成周报包含 1. 本周重点工作方向归纳 2. 按功能模块整理的具体事项 3. 需要关注的风险或遗留问题 4. 下周计划建议 5. 不要包含代码细节用面向管理者的语言; }这个脚本用git config user.name自动识别当前用户不用手动填名字。模型拿到的提交记录已经过滤到个人这样生成的周报内容准确度很高。需要注意的是如果团队里大家共用 Git 账号这个命令的准确性就会打折扣需要改成按邮箱或 ID 过滤。4.4 项目导读命令让新人快速上手老项目最后一个我重点讲讲/导读命令。接手过老项目的人应该深有体会一个新仓库除了 README 里那几句话什么引导都没有。AI 编程工具的作用在这里尤为突出——它可以快速消化数百个文件。导读.ts脚本会做以下事import * as cp from child_process; export async function main(args: string[]): Promisestring { const topDir args[0] || ./src; // 默认看 src 目录 // 先拿目录树 const tree cp.execSync(find ${topDir} -maxdepth 3 -type f | head -100, { encoding: utf-8 }); // 关键入口文件的读取策略 // 1. package.json 或 go.mod 看依赖 // 2. 入口文件常叫 main / index / app优先看 // 3. 配置文件如 .env.example 提供环境变量线索 const entryFiles [package.json, go.mod, main.ts, main.go, index.ts, app.py, .env.example] .filter(f { try { return require(fs).existsSync(f); } catch { return false; } }) .map(f ### ${f}\n${require(fs).readFileSync(f, utf-8).slice(0, 1000)}) .join(\n\n); return 项目目录树前三层 ${tree} 关键配置文件与入口文件内容 ${entryFiles} 请根据以上信息输出 1. 项目的技术栈与架构模式 2. 核心领域模型结合文件名推测 3. 请求/事件的处理流程概述 4. 常见修改场景的切入点说明比如新增接口、改数据库字段、加定时任务 5. 针对新人的上手步骤建议; }这个命令的核心价值在于把人肉通读项目的过程压缩为一次对话。模型会依据目录结构和核心配置推断出项目的设计意图。比如看到src/controllers/、src/services/、src/models/这样的目录就能判断这是一个典型 MVC 分层结构看到go.mod里的依赖就能判断项目是否用了特定的 Web 框架、ORM 和消息队列。对新人来说这份“导读”比让资深同事讲半小时更具体。对有经验的开发者来说它的价值是快速判断一个项目值不值得深入。5. 常见问题与排查技巧实录5.1 命令不生效或列表不显示最常遇到的坑是文件放进.claude/commands/了但输入/看不到命令。这个问题的排查路径一般是看命令文件命名。Claude Code 要求命令文件名不能包含空格和中划线。中文文件名可以用但中间不能有特殊字符。文件名的数字会作为参数编号。比如审查_1.md这样的名字不合法改成审查1.md就正常。检查目录位置。命令文件必须在.claude/commands/下不能放在子目录里。子目录虽然能放但不会出现在命令列表中。重启 Claude Code 会话。老版本的 Claude Code 不会热加载新命令文件必须重启会话才能识别。提示如果你用 VS Code 集成终端跑 Claude Code重启会话不一定要重启 VS Code只要退出claude重新敲一遍即可。5.2 TypeScript 脚本执行报错脚本执行失败时错误信息会直接显示在终端通常是 Node.js 的堆栈。最常见的几类问题Cannot find module child_process理论上内置模块都存在但如果你在.ts文件顶部写了import ... from语法必须确保环境支持 TypeScript 编译。Claude Code 内部会自动转译但有时会因为项目里有自己的 tsconfig 产生冲突。稳妥做法是在ts文件里用require而非import。Standard output is empty这是典型的返回值问题。如果你在 main 函数里没有返回字符串或者返回 undefined脚本就会报这个错。检查一下 main 函数的写法确保所有路径都有返回值。Maximum buffer exceeded抓取超大文件或超长 Diff 时常见。通过maxBuffer参数调大缓冲区即可但不要无脑调大建议根据项目规模在 5MB 到 20MB 之间设置。脚本有语法错误时错误提示有时不明显只会提示执行失败。这时可以把.ts临时改成.js文件用 Node 直接跑一遍看具体报错定位后再改回来。5.3 上下文窗口被无效内容塞满命令脚本返回的内容会占用上下文空间如果脚本太“贪婪”把大量无关代码塞给模型后面的对话质量会直线下降。这是我踩过最深的坑。典型场景是/审查命令当时我把完整 Diff 直接传给模型结果有一次的 Diff 有 30000 多行导致后续的对话里模型总是把旧代码遗忘还出现幻觉。用截断策略后效果稳定很多。经验数据可以参考Diff 行数范围截断策略0-500 行完整保留不截断500-2000 行保留前后各 40%中间摘要2000 行以上只保留统计和关键文件列表5.4 命令执行的权限确认弹窗干扰Claude Code 默认对脚本执行有权限确认机制如果你调的命令涉及执行git或读文件每个操作都会弹窗确认。这在实际使用中很烦人尤其是命令脚本里有两三个execSync调用时会连续弹窗好多次。解决方式就是前面说的在.claude/settings.json里配置allow列表。把命令所需的读类操作全部加进去。注意Bash(git diff:*)和Bash(git log:*)这类规则要精确不要图省事写Bash(*)否则等于完全放弃权限控制。5.5 不同系统和 Windows 环境的兼容性差异我日常主要用 macOS 或 Linux但热词列表里很多人关心 Windows 配置。Claude Code 在 Windows 下确实有兼容面问题但也不是不能解决。关键差异点Windows 下执行git diff的路径分隔符不同脚本里建议用path.join或path.resolve统一处理而不是硬编码/分隔。默认命令解释器不同Windows 默认用cmd.exe有时sed、awk这类命令不可用。如果脚本里用到这些命令先设置SHELL环境变量或者改用纯 node 实现。中文路径文件名在 Windows 下有编码差异搜索时注意用utf-8编码规则。建议在 Windows 上不要完全跳过权限确认因为某些安全策略的差异会让跳过权限更容易出问题。这一点对不同系统的兼容性我特意让我一个 Windows 环境的同事跑过一遍全部命令修改了脚本中涉及find、awk的管道逻辑用相对简单的方式重写后Windows 下也能稳定运行。5.6 命令使用的频率控制与疲劳问题这套工作流包有个隐藏问题命令太方便了会让人产生路径依赖。我有段时间甚至懒得自己看代码遇到什么先敲一遍命令再说结果越用越依赖自己的代码理解能力反而退化了。感受最深的是在排查一个线上问题时Claude 给出了看似合理的定位但验证时发现它推测的调用链是错的。那次之后我给自己定了一个规矩/审查的结果只作为辅助参考关键改动必须自己读一遍 Diff 和核心函数。AI 编程工具是放大器不是方向盘。放大的是你的工作效率但如果方向错了工具只能让你更快地跑向错误的地方。6. 扩展方向把工作流包从“个人玩具”升级为“团队基建”6.1 接入本地模型与私有化推理如果对数据安全有要求可以不使用 Claude 云端模型而是调用本地模型。Claude Code 支持配置自定义推理端点比如接入 LM Studio 这类本地模型服务。这个方向的好处是代码完全不出内网适合涉及敏感数据的项目。坏处也很明显本地模型的推理能力通常不如云端复杂代码审查任务的效果会大幅缩水。我的建议是分场景对简单的提交信息生成、文档生成、周报等任务本地模型的 response 时间足够且效果不差但对代码审查、缺陷定位这类需要深度理解的任务还是应该使用最强模型。可以这样按命令设置模型组/提交和/周报走本地模型/审查和/定位走云端模型。这样既控制了成本又保证了关键任务的质量。6.2 命令的自定义与团队模板沉淀团队使用的过程中命令会自然分化为“个人版”和“团队版”。我自己的实践是每个团队项目管理的关键命令从 10 个精简到 5 个——审查、定位、提交、周报、导读——剩下的归类为个人扩展命令。团队版本由一个人维护变更后通过 Git 合并到主干其他人git pull自动更新。另外可以考虑增加一个/模板命令它不做任何分析只是输出一组标准的 Markdown 模板包含代码 review 清单、项目交接文档、故障报告等。这个命令的价值不在于“智能”而在于统一团队的文档结构。时间长了团队产出的文档风格会非常一致后续检索和维护都省心很多。6.3 未来扩展定时任务与自动流程目前这套工作流包全部是“对话时触发”没有做到主动触发。后续可以考虑扩展的方向是把命令接入到 CI 流程中比如每次 MR 创建后自动触发/审查把审查结果写到 MR 评论里。也可以写一个定时任务每周五下午自动跑/周报把生成的内容推送到团队群。这些扩展的实现路径会复杂一些已经不是单纯的 Claude Code 范畴。但从实际收益看越往这个方向走效率提升越明显。代码质量检查从“人肉主动”变成“自动被动”工作流本身的维护成本也大幅下降。写在最后的实操体会这套 10 个中文命令组成的 Claude Code 工作流包用到现在大概三个月。我的体会是AI 编程工具的潜力很大程度上取决于你怎么包装它。同一套模型一个什么都不配置的人可能觉得它只是高级一点点的搜索引擎但一个把命令、权限、上下文管理都调好的人能把它用成真正意义上的“团队高级工程师”——能审查、能定位、能写文档、能出周报。如果你是刚接触 Claude Code我的建议特别简单今天先别写十个命令就写一个。挑你最痛的那个环节比如提交信息总是被吐槽那就先做一个/提交命令。跑通一次感受一下“输入两句话输出一段规范文案”的体验之后再逐步扩充。命令不是越多越好顺手才是硬道理。 Claude Code中文工作流包：10个Slash Command提升开发效率
Claude Code 折腾了一阵子我一直觉得这工具好用是好用但每次输入命令都得憋英文还要在脑子里过一遍 Prompt 模板有点累。后来干脆花了两个周末把日常最常用的操作全部封装成了带中文提示的 Slash Command一共 10 个做成了一个可以直接拷到项目里用的工作流包。这文章不是讲概念就是把这 10 个命令的设计思路、配置文件写法、踩过的坑完整摊开给同样在用 Claude Code 写代码、做 Code Review、理项目的人一个能直接抄作业的参考。先说清楚这套东西解决什么问题很多人把 Claude Code 当成一个高级聊天框来用问一句答一句完全没有发挥出它真正的优势。它其实支持自定义命令可以把复杂的 Prompt、固定的处理流程、甚至本地脚本全部打包成一个短命令输入/修复就能触发一整套 Bug 分析流程而不是每次手动敲一大段话。10 个中文命令做完后我的日常协作流程变成了三步写完代码敲/审查开会前敲/周报接手老项目敲/导读。效率提升是实打实的更关键的是这套做法让没有提示词经验的同事也能轻松上手。1. 整体设计为什么要把命令做成中文 Slash 命令1.1 Claude Code 的原生命令机制这一节先介绍背景知识用过的朋友可以跳过。Claude Code 支持自定义 Slash Command命令文件放在项目根目录的.claude/commands/下每个命令由markdown提示词文件和可选的TypeScript脚本文件组成。你在对话框输入/某某时Claude Code 会自动读取对应的 Markdown 内容把其中的参数替换成你实际输入的值然后作为系统提示词的一部分发给大模型。这套机制比我一开始以为的“预置 Prompt 模板”要强得多。Markdown 文件只是静态文本真正让它活起来的是旁边的.ts脚本文件。脚本可以读取当前项目的文件状态、Git 暂存区内容、甚至执行终端命令把结果拼接到提示词里再发给模型。这意味着我可以在命令里写“请分析以下 Git Diff”然后脚本自动把git diff --cached的输出塞进去。原生机制里还有几个细节值得注意。命令文件区分全局和项目级全局命令放在~/.claude/commands/所有项目可用项目级放在项目根目录适合和团队共享。命令参数通过$ARGUMENTS传递文件名中的数字会作为参数编号。这些细节在后面配置时会反复用到。1.2 选择中文命名的三个决定性理由第一个理由是团队协作门槛。我们小组六个人真正写过 Prompt 的不到一半大部分同事对 AI 工具的态度是“能用但不想折腾”。如果我给他们分享的是一堆英文 Prompt 模板基本等于没分享。但如果是/审查、/周报这样的中文命令只要看一眼列表就能猜到功能用一次就能记住。这个差别在团队落地时是决定性的。第二个理由是记忆成本。我知道很多人觉得英文命令更“正统”但作为一天要敲几十次命令的人来说记忆负荷是真实存在的。尤其在上下文切换频繁的时候脑子里要同时装业务逻辑和命令语法很容易卡壳。中文命令天然符合我的思维习惯。更重要的是Claude Code 的模型本身对中文理解力很强命令名用什么语言对它来说没有区别但这降低了我的工作记忆负担。第三个理由是语义完整性。英文 Slash Command 往往受限于单词长度比如/review、/fix、/log这些缩写能表达功能但不表达场景。中文命令可以用“审查代码”“梳理日志”“生成周报”这样的动宾结构信息密度更高。当一个命令包含多个操作步骤时中文命名能把整个流程的目的直接表达出来这比一个含糊的英文单词要清楚得多。1.3 十个命令的全景地图我最终保留了 10 个命令按照使用频率和场景分成四类。先给你一张全景表后面每一类再展开讲。命令名称触发方式核心功能适用场景代码审查/审查 [范围]检查本地修改或指定文件输出代码问题清单提交前自检、MR 前预审缺陷定位/定位 [现象]根据错误信息或现象描述定位代码中可能的问题点线上 Bug 排查、报错处理提交信息/提交 [描述]生成符合 Conventional Commits 规范的提交说明Git 提交前提交记录/历史 [范围]分析 Git 提交历史输出提交规律与问题总结版本回顾、绩效总结差异解读/变更 [文件]解释工作区与暂存区的代码改动意图Code Review 辅助重构规划/重构 [目标]输出重构方案包含步骤拆解、风险影响、验证方案技术债清理文档生成/文档 [模块]为目标代码模块生成 README 与接口说明新模块交付、交接项目导读/导读通读项目结构输出架构说明与新手指南新人接手、快速上手周报助手/周报分析本周提交记录生成工作总结周报撰写学习助手/教学 [主题]解释项目中的特定技术概念附带项目内实例技术学习、新人培训这张表里前四个是高频使用的“主力命令”几乎每天都会碰中间三个是“低频高价值命令”虽然用得少但每次都能省半小时以上最后三个是“团队协作命令”主要给非核心开发人员用。2. 核心实现三个高频命令的逐行拆解2.1 代码审查命令的完整实现代码审查命令是我最早实现的一个也是迭代次数最多的。它的核心思路是让 Claude Code 扮演资深 Reviewer 的角色对指定范围的代码进行审查输出问题清单而非泛泛而谈。先看目录结构这是标准做法.claude/commands/ ├── 审查.md ├── 审查.ts ├── 定位.md ├── 定位.ts └── ...审查.md的内容如下你是一名拥有 15 年经验的资深代码审查专家擅长发现潜在 Bug、安全隐患和性能瓶颈。 请审查以下范围内的代码变更重点关注 1. 逻辑错误与边界条件空值、并发、溢出等 2. 安全隐患注入、敏感信息泄露、越权访问 3. 性能问题不必要的大对象创建、循环内查询、N1 问题 4. 代码风格与可维护性命名、重复代码、魔法数字 5. API 设计的合理性参数校验、返回值定义 输出格式 - 按严重程度分为【阻断级】【建议级】【优化级】 - 每个问题需要给出文件路径、行号如可定位、问题描述、修改建议 - 如果审查范围内没有问题请明确说明不要为了凑数而输出无意义建议 审查范围$ARGUMENTS这里的核心是$ARGUMENTS变量。用户在输入/审查 全部时这个变量会被替换成“全部”输入/审查 src/utils.ts时会被替换成文件路径。但标记文件里不能执行任何代码真正去拉取 Git Diff 的工作要由 TypeScript 脚本来做。审查.ts的核心逻辑如下import * as cp from child_process; import * as fs from fs; import * as path from path; function getGitDiff(scope: string): string { // git diff 是核心数据源只审查未提交的改动 const args scope 全部 ? [diff, --cached] : [diff, --cached, --, scope]; const output cp.execSync(git ${args.join( )}, { encoding: utf-8, maxBuffer: 10 * 1024 * 1024 // 大项目 diff 很容易超默认 buffer }); return output; } function truncate(text: string, maxLen: number 12000): string { // 超过上下文窗口的直接舍弃中间部分保留开头和结尾 if (text.length maxLen) return text; const half Math.floor(maxLen / 2); return text.slice(0, half) \n\n...[中间内容已省略]...\n\n text.slice(-half); } export async function main(args: string[]): Promisestring { const scope args.join( ) || 全部; // 也要包含暂存区状态以外的上下文信息 const branch cp.execSync(git branch --show-current, { encoding: utf-8 }).trim(); const lastCommit cp.execSync(git log -1 --oneline, { encoding: utf-8 }).trim(); const diff getGitDiff(scope); return 当前分支${branch} 最近提交${lastCommit} 审查范围${scope} ${truncate(diff)}; }这个脚本做的事情非常简单把 Git Diff 抓取出来加上当前分支名和最近提交信息一并交给 Claude。关键点在于truncate函数这是我在实践中发现的硬性需求。没有它时遇到大型项目的一次提交动辄几万字符的 DiffClaude 的上下文窗口会被大量无关代码刷屏导致真正重要的逻辑反而不被关注。截断后虽然丢失了中间细节但模型能集中精力处理改动上下文的关键部分效果反而更稳定。还有个细节我要特别提示git diff --cached只审查暂存区的改动不审查工作区未暂存的部分。这种设计是有意的因为暂存区内容往往是提交意图较明确的代码。但我后来发现很多人用命令时不习惯先git add所以我在审查.ts里做了逻辑调整如果暂存区为空就自动改为对比工作区和 HEAD。这个适应性逻辑极大减少了误操作率。2.2 缺陷定位命令把问题描述转换为代码路径缺陷定位命令解决的是最让人头疼的排查环节线上报了一个错错误信息很抽象只知道大概发生在哪个模块但要找到具体代码位置往往要翻半天日志。这条命令的设计思路是“现象输入路径输出”。定位.md的内容你是一个资深 Debug 专家。根据用户描述的错误现象结合项目代码结构进行以下分析 1. 根据异常信息的关键词推测可能出错的函数调用链路 2. 在项目代码中搜索与错误相关的函数、变量、异常类 3. 根据调用关系判断最可能的出错位置 4. 给出 2-3 个可疑点每个可疑点包含文件路径、函数名、行号如可定位、出错概率、排查建议 注意 - 如果错误信息中包含堆栈片段优先从堆栈线索入手 - 不要给无关的全局建议一定要定位到具体文件和函数 - 如果无法定位列出你搜索过哪些关键词和文件帮助用户进一步提供信息 错误现象$ARGUMENTS定位.ts的实现逻辑就更复杂一些因为要主动搜索代码内容import * as cp from child_process; import * as fs from fs; import * as path from path; const IGNORE_DIRS [node_modules, dist, build, .git, vendor, __pycache__]; function searchInFiles(needle: string): string[] { // 这里有两个搜索策略文件名匹配 和 内容匹配 const results: string[] []; const needleLower needle.toLowerCase(); // 策略一在文件内容里搜关键词用 ripgrep 效率高很多 try { const rgOutput cp.execSync(rg -l -i ${needle} --type-add web:*.{ts,tsx,js,jsx,vue,py,java,go} -t web . 2/dev/null | head -30, { encoding: utf-8, maxBuffer: 5 * 1024 * 1024 }); results.push(...rgOutput.trim().split(\n).filter(Boolean)); } catch { // ripgrep 没装或没有匹配都会走到这里 } // 策略二按文件名匹配 const files walkSync(./src, 4); // 限制深度避免遍历整个 node_modules for (const file of files) { const base path.basename(file); if (base.includes(needle) || needleLower.includes(base.replace(/\.[^.]$/, ).toLowerCase())) { results.push(file); } } return [...new Set(results)]; } function walkSync(dir: string, maxDepth: number): string[] { // 一个简单的递归遍历函数再加个深度限制防止爆掉 if (maxDepth 0) return []; const files: string[] []; if (!fs.existsSync(dir)) return files; for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { const full path.join(dir, entry.name); if (IGNORE_DIRS.includes(entry.name)) continue; if (entry.isDirectory()) { files.push(...walkSync(full, maxDepth - 1)); } else if (entry.isFile()) { files.push(full); } } return files; } export async function main(args: string[]): Promisestring { const description args.join( ) || 未提供错误现象; const searchTerms description .split(/\s/) .filter(term term.length 1) .slice(0, 5); // 最多取5个关键词不然搜索范围太大 const foundedFiles: string[] []; for (const term of searchTerms) { foundedFiles.push(...searchInFiles(term)); } const uniqueFiles [...new Set(foundedFiles)].slice(0, 30); // 读几个候选文件的头部给模型一些结构线索 const fileSnapshots uniqueFiles.slice(0, 5).map(file { try { const content fs.readFileSync(file, utf-8).slice(0, 1500); return ### ${file}\n${content}; } catch { return ; } }).join(\n\n); return 错误现象${description} 在项目中找到以下可能相关的文件 ${uniqueFiles.length 0 ? uniqueFiles.join(\n) : 未找到匹配文件请检查关键词或扩大搜索范围。} 其中部分文件的内容预览如下 ${fileSnapshots || 无可用预览} ; }这里我用了一个组合搜索策略先用ripgrep搜内容匹配再用路径遍历做文件名匹配。为什么要两套方案因为错误信息里的关键词经常不是文件名而是异常类名、接口名、或者中文字段名。rg搜内容能覆盖这类情况但不一定每个环境都装了 ripgrep而且大目录全量搜索很慢。文件名的匹配虽然覆盖率低但执行速度快两者互补。另外一个值得一提的取舍是walkSync的深度限制。如果项目采用平铺结构深度 1-2 就能找到如果项目嵌套深4 层是合理上限。再深基本都是业务代码的分包目录对定位帮助不大还会因遍历过慢影响命令响应速度。这些细节看着琐碎实际用起来区别很大。2.3 提交信息命令让 Git 提交从憋文案变成填空这条命令做的是最基础但最烦人的事。很多人提交代码时提交信息随便写个fix bug或update团队看历史记录时一头雾水。这条命令用 Claude 理解 Diff 内容自动生成规范提交信息。提交.md根据代码变更内容生成符合 Conventional Commits 规范的提交信息。 要求 1. type 限用feat / fix / refactor / docs / chore / perf / test 这七种 2. 简要描述中英文混合中文为主体动词开头不超过 20 个汉字 3. 在提交信息中说明修改的核心文件和影响函数 4. 如果有破坏性变更需要在正文中用 BREAKING CHANGE: 标记 5. 最终输出只保留提交信息原文不要增加任何解释你的思路的内容 变更描述如为空则自动分析 $ARGUMENTS提交.ts的主要逻辑import * as cp from child_process; export async function main(args: string[]): Promisestring { const userDescription args.join( ); // 这里做的是增强版 diff 摘要比把完整 diff 直接扔给模型效果更好 let diff ; try { diff cp.execSync(git diff HEAD --stat, { encoding: utf-8 }).trim(); // 加上实际文件变更比率的参数据让模型更好判断本次修改的规模 const diffSummary cp.execSync(git diff HEAD --dirstatfiles,0, { encoding: utf-8 }).trim(); diff \n\n目录变更统计:\n diffSummary; } catch { diff 无 Git 信息; } return 用户描述${userDescription || 未提供请直接从 Diff 中分析} ## 本次变更统计 ${diff} ## 请基于以上信息生成提交信息。; }这里没有把整个 Diff 交给模型只给了--stat的统计即文件和行数变化。这么做省 token 而且效果不差。模型根据文件变更列表加上用户的一句话描述已经足够产出合理的提交类型判断。把整个 Diff 塞进去反而会产生噪音比如模型会盯着某些具体实现细节反而忽视了整体变更意图。产出提交信息后用户可以直接复制使用也可以跟我给的模板对比调整。这个命令看着简单但它的实际效果非常稳定因为提交信息生成是一个极度适合 LLM 的任务——不需要深度推理只需要概括归纳。3. 配置与安装从零搭建完整的命令工作流包3.1 配置文件目录结构与全局命令安装这套工作流包的核心文件全部放在.claude/commands/下。如果只是想自己用可以放到全局目录~/.claude/commands/这样所有项目都能共用。如果是要给团队共享建议提交到仓库里放在项目根目录下配合团队的.claude/settings.json配置文件一起使用。团队的共享场景里还要注意一点很多人会直接在项目里修改.claude下的文件导致团队命令版本不一致。我建议命令文件尽量放在独立的私有目录维护通过构建脚本部署到项目里或者直接以文件方式共享让每个人自己安装。这个选择虽然多了一步操作但避免了“我在你机器上改了命令你机器上是旧的而且完全不知道差异在哪”的尴尬局面。配置文件这块一个常见需求是设置命令权限。Claude Code 默认在执行脚本类命令时会弹出确认框有些团队希望静默执行。这时可以在.claude/settings.json中配置权限{ permissions: { allow: [ Bash(git diff:*), Bash(git log:*), Bash(rg:*), Read(*) ], deny: [ Bash(git push:*), Bash(git reset:*), Bash(rm:*) ] } }这个配置的意思是允许读取文件、查看 Git Diff 和日志、搜索代码禁止推送、硬重置和删除操作。我强烈建议任何团队都做一层这样的限制因为 Claude Code 为了完成“分析任务”可能需要读文件但完全没有理由执行推送或删除命令。权限配置不花一分钟但能挡住很多误操作。3.2 命令的运行机制Markdown 与 TypeScript 的分工边界这是理解 Claude Code 的自定义命令最核心的一点md文件与ts文件的职责边界。我从多次迭代中总结的经验是Markdown 文件的职责是定义模型的角色、任务和约束。它所有的文字都会传给 Claude作为系统提示词的一部分。要注意的是这个文件里不能直接执行任何命令它的作用是告诉模型要做什么。TypeScript 文件的职责是提供数据、执行系统操作。它会在 Claude 开始处理之前执行产生的返回值会作为一个特殊消息注入到上下文中。主函数通常接受args(string[])作为参数这个参数就是用户在命令后输入的内容。两者之间的配合逻辑是这样的在/审查命令里审查.md描述代码审查专家的行为和输出格式而审查.ts抓取 Git Diff 的实际数据把数据加进上下文中。模型拿到数据和任务指令后输出最终的审查结果。没有.ts文件的命令也可以正常运行$ARGUMENTS会被用户输入替换但无法动态抓取项目状态。关于 TypeScript 文件的几个实操要点ts文件的入口函数必须是main(args: string[]): Promisestring返回值会被拼接到上下文中。ts文件通过 Node.js 执行所有 Node 内置模块都能直接用。文件内不要写 console.log输出结果应通过返回值传递。命令执行环境是项目根目录所以相对路径不会出错。脚本异常时命令会失败但不会中断 Claude Code 主进程。这些约定最初我花了不少时间摸索因为官方文档并不会明确告诉你返回值如何连接提示词。实践中试错几轮后我总结成上面这几条基本涵盖了 90% 的场景。3.3 与 Visual Studio Code 的联动配置我在日常开发中用 Visual Studio Code 自带的终端来跑 Claude Code这个组合体验不错。关键要在 VS Code 的集成终端里允许 Claude Code 使用快捷命令以及配置好终端会话的保持。具体的配置方式是在 VS Code 的settings.json里设置{ terminal.integrated.env.windows: { CLAUDE_CODE_OPTS: --dangerously-skip-permissions } }注意这里--dangerously-skip-permissions是跳过权限确认适合个人开发环境使用。如果团队协作建议不要开这个选项而是在settings.json里精确配置允许列表前面说的权限配置就是这个用途。另外我习惯把 Claude Code 单独放到一个终端标签页并给它设置一个独立的配色避免跟其他终端输出混在一起。VS Code 的终端界面支持多标签在terminal.integrated.tabs里可以把 Claude Code 的会话固定住这样随时敲命令都不用找。3.4 一个完整的命令部署流程示例假设你要把整套工作流包部署到一个新成员电脑上最稳妥的手动流程是这样的先安装 Claude Codenpm install -g anthropic-ai/claude-code克隆项目到本地执行claude初始化复制命令目录把.claude/commands/整个文件夹放到项目根目录注意不要覆盖别人已经改过的配置检查settings.json权限配置确保Bash(git diff:*)等允许规则在里面在项目目录运行claude输入/查看命令列表是否出现中文命令先跑一遍/文档 当前目录做一个冒烟测试确认 TypeScript 脚本能正常执行这个流程我已经给组里新人走过三轮基本上没有盲点。4. 实操过程与核心环节实现4.1 一次完整的代码审查实战记录为了让你对这套工作流包有更直观的感受我记录一次真实的/审查操作过程。那天的场景是一个变更涉及用户登录模块修改了验证码校验逻辑和 Token 刷新机制。我在终端输入/审查命令执行后终端会把审查.ts抓取到的 Git Diff 与审查.md的命令文本合并作为上下文模型开始分析。大约 10 秒后输出了一份报告其中有一条我印象很深【阻断级】verifyCode.ts第 89 行验证码校验失败时直接抛出异常导致整个登录请求回滚但在验证码校验之前已经被查询的验证码记录、尝试次数等信息处于未清理状态极端并发场景下可能导致验证码记录泄漏。这条我确实没想到。原代码里验证码校验失败就立刻抛出业务异常框架层会做事务回滚但那张记录验证码的表因为事务隔离级别的问题在特定数据库配置下并不会完全回滚。这种场景靠人肉一眼看出很难但 LLM 结合了代码上下文之后真的能找到这种跨模块的隐蔽问题。模型还正确识别了一个潜在安全风险——在重置 Token 之前没有校验旧 Token 是否已经过期给重放攻击留了窗口。这两条建议都直接提进了 MR 里同事看到后立刻调整了逻辑。自从团队开始用/审查大家可以明显感受到提交前的隐患变少了。4.2 缺陷定位命令的高效排查实例有一次后台报了个杂音错误日志里反复出现JSON parse error: Unexpected token但是没有明确堆栈。我直接敲了/定位 JSON parse error 日志上传。命令脚本把这三个关键词并行搜索了一遍。结果性能非常明显因为我的日志上传模块里有一段手写的 JSON 序列化逻辑它拼 SQL 的时候不小心在字符串数组里留下了尾逗号PHP 那边解析到数组最后一个位置时直接挂了。如果没有这套命令靠手动打开项目反复搜索关键词至少要到 5-10 分钟甚至更久。一个命令下去3 秒就列出 6 个可疑文件我打开第一个就找到了问题。这里有个使用场景要提示命令的效果跟错误描述的信息量强相关。如果只知道报错了模型也只能瞎猜。我总结了一句口诀报错信息要给出【异常类型 关键词 大概功能模块】准确率翻倍。比如上面的JSON parse error 日志上传就包含了这三类信息。4.3 周报助手命令的团队落地效果这个命令是我意料之外好评最多的一个。起因是我发现每个周五写周报都要打开 Git 记录整理提交信息步骤繁杂。后来我写了/周报命令脚本自动统计当前用户本周的提交记录按日期分组输出每个提交的标题、影响文件、关联的 MR 号。模型再将这些内容整理成周报格式。周报.ts的核心逻辑import * as cp from child_process; export async function main(args: string[]): Promisestring { // 默认统计本周一到今天 const monday new Date(); const day monday.getDay(); const diff day 0 ? 6 : day - 1; monday.setDate(monday.getDate() - diff); monday.setHours(0, 0, 0, 0); const since args[0] || monday.toISOString().slice(0, 10); // git log 按作者 时间过滤 const author cp.execSync(git config user.name, { encoding: utf-8 }).trim(); const log cp.execSync( git log --author${author} --since${since} 00:00:00 --untilnow --prettyformat:%h %ad %s --dateformat:%Y-%m-%d %H:%M, { encoding: utf-8, maxBuffer: 10 * 1024 * 1024 } ).trim(); // 统计每个文件的变更行数, 给周报提供更具体的数据 const stat cp.execSync( git log --author${author} --since${since} 00:00:00 --numstat --prettyformat:%h | awk /^[0-9]/ {added$1; deleted$2} END {print added, deleted}, { encoding: utf-8, maxBuffer: 5 * 1024 * 1024 } ).trim(); return 本周起始日期${since} 提交记录 ${log} 变更统计新增行数 删除行数${stat} 请把以上内容整理成周报包含 1. 本周重点工作方向归纳 2. 按功能模块整理的具体事项 3. 需要关注的风险或遗留问题 4. 下周计划建议 5. 不要包含代码细节用面向管理者的语言; }这个脚本用git config user.name自动识别当前用户不用手动填名字。模型拿到的提交记录已经过滤到个人这样生成的周报内容准确度很高。需要注意的是如果团队里大家共用 Git 账号这个命令的准确性就会打折扣需要改成按邮箱或 ID 过滤。4.4 项目导读命令让新人快速上手老项目最后一个我重点讲讲/导读命令。接手过老项目的人应该深有体会一个新仓库除了 README 里那几句话什么引导都没有。AI 编程工具的作用在这里尤为突出——它可以快速消化数百个文件。导读.ts脚本会做以下事import * as cp from child_process; export async function main(args: string[]): Promisestring { const topDir args[0] || ./src; // 默认看 src 目录 // 先拿目录树 const tree cp.execSync(find ${topDir} -maxdepth 3 -type f | head -100, { encoding: utf-8 }); // 关键入口文件的读取策略 // 1. package.json 或 go.mod 看依赖 // 2. 入口文件常叫 main / index / app优先看 // 3. 配置文件如 .env.example 提供环境变量线索 const entryFiles [package.json, go.mod, main.ts, main.go, index.ts, app.py, .env.example] .filter(f { try { return require(fs).existsSync(f); } catch { return false; } }) .map(f ### ${f}\n${require(fs).readFileSync(f, utf-8).slice(0, 1000)}) .join(\n\n); return 项目目录树前三层 ${tree} 关键配置文件与入口文件内容 ${entryFiles} 请根据以上信息输出 1. 项目的技术栈与架构模式 2. 核心领域模型结合文件名推测 3. 请求/事件的处理流程概述 4. 常见修改场景的切入点说明比如新增接口、改数据库字段、加定时任务 5. 针对新人的上手步骤建议; }这个命令的核心价值在于把人肉通读项目的过程压缩为一次对话。模型会依据目录结构和核心配置推断出项目的设计意图。比如看到src/controllers/、src/services/、src/models/这样的目录就能判断这是一个典型 MVC 分层结构看到go.mod里的依赖就能判断项目是否用了特定的 Web 框架、ORM 和消息队列。对新人来说这份“导读”比让资深同事讲半小时更具体。对有经验的开发者来说它的价值是快速判断一个项目值不值得深入。5. 常见问题与排查技巧实录5.1 命令不生效或列表不显示最常遇到的坑是文件放进.claude/commands/了但输入/看不到命令。这个问题的排查路径一般是看命令文件命名。Claude Code 要求命令文件名不能包含空格和中划线。中文文件名可以用但中间不能有特殊字符。文件名的数字会作为参数编号。比如审查_1.md这样的名字不合法改成审查1.md就正常。检查目录位置。命令文件必须在.claude/commands/下不能放在子目录里。子目录虽然能放但不会出现在命令列表中。重启 Claude Code 会话。老版本的 Claude Code 不会热加载新命令文件必须重启会话才能识别。提示如果你用 VS Code 集成终端跑 Claude Code重启会话不一定要重启 VS Code只要退出claude重新敲一遍即可。5.2 TypeScript 脚本执行报错脚本执行失败时错误信息会直接显示在终端通常是 Node.js 的堆栈。最常见的几类问题Cannot find module child_process理论上内置模块都存在但如果你在.ts文件顶部写了import ... from语法必须确保环境支持 TypeScript 编译。Claude Code 内部会自动转译但有时会因为项目里有自己的 tsconfig 产生冲突。稳妥做法是在ts文件里用require而非import。Standard output is empty这是典型的返回值问题。如果你在 main 函数里没有返回字符串或者返回 undefined脚本就会报这个错。检查一下 main 函数的写法确保所有路径都有返回值。Maximum buffer exceeded抓取超大文件或超长 Diff 时常见。通过maxBuffer参数调大缓冲区即可但不要无脑调大建议根据项目规模在 5MB 到 20MB 之间设置。脚本有语法错误时错误提示有时不明显只会提示执行失败。这时可以把.ts临时改成.js文件用 Node 直接跑一遍看具体报错定位后再改回来。5.3 上下文窗口被无效内容塞满命令脚本返回的内容会占用上下文空间如果脚本太“贪婪”把大量无关代码塞给模型后面的对话质量会直线下降。这是我踩过最深的坑。典型场景是/审查命令当时我把完整 Diff 直接传给模型结果有一次的 Diff 有 30000 多行导致后续的对话里模型总是把旧代码遗忘还出现幻觉。用截断策略后效果稳定很多。经验数据可以参考Diff 行数范围截断策略0-500 行完整保留不截断500-2000 行保留前后各 40%中间摘要2000 行以上只保留统计和关键文件列表5.4 命令执行的权限确认弹窗干扰Claude Code 默认对脚本执行有权限确认机制如果你调的命令涉及执行git或读文件每个操作都会弹窗确认。这在实际使用中很烦人尤其是命令脚本里有两三个execSync调用时会连续弹窗好多次。解决方式就是前面说的在.claude/settings.json里配置allow列表。把命令所需的读类操作全部加进去。注意Bash(git diff:*)和Bash(git log:*)这类规则要精确不要图省事写Bash(*)否则等于完全放弃权限控制。5.5 不同系统和 Windows 环境的兼容性差异我日常主要用 macOS 或 Linux但热词列表里很多人关心 Windows 配置。Claude Code 在 Windows 下确实有兼容面问题但也不是不能解决。关键差异点Windows 下执行git diff的路径分隔符不同脚本里建议用path.join或path.resolve统一处理而不是硬编码/分隔。默认命令解释器不同Windows 默认用cmd.exe有时sed、awk这类命令不可用。如果脚本里用到这些命令先设置SHELL环境变量或者改用纯 node 实现。中文路径文件名在 Windows 下有编码差异搜索时注意用utf-8编码规则。建议在 Windows 上不要完全跳过权限确认因为某些安全策略的差异会让跳过权限更容易出问题。这一点对不同系统的兼容性我特意让我一个 Windows 环境的同事跑过一遍全部命令修改了脚本中涉及find、awk的管道逻辑用相对简单的方式重写后Windows 下也能稳定运行。5.6 命令使用的频率控制与疲劳问题这套工作流包有个隐藏问题命令太方便了会让人产生路径依赖。我有段时间甚至懒得自己看代码遇到什么先敲一遍命令再说结果越用越依赖自己的代码理解能力反而退化了。感受最深的是在排查一个线上问题时Claude 给出了看似合理的定位但验证时发现它推测的调用链是错的。那次之后我给自己定了一个规矩/审查的结果只作为辅助参考关键改动必须自己读一遍 Diff 和核心函数。AI 编程工具是放大器不是方向盘。放大的是你的工作效率但如果方向错了工具只能让你更快地跑向错误的地方。6. 扩展方向把工作流包从“个人玩具”升级为“团队基建”6.1 接入本地模型与私有化推理如果对数据安全有要求可以不使用 Claude 云端模型而是调用本地模型。Claude Code 支持配置自定义推理端点比如接入 LM Studio 这类本地模型服务。这个方向的好处是代码完全不出内网适合涉及敏感数据的项目。坏处也很明显本地模型的推理能力通常不如云端复杂代码审查任务的效果会大幅缩水。我的建议是分场景对简单的提交信息生成、文档生成、周报等任务本地模型的 response 时间足够且效果不差但对代码审查、缺陷定位这类需要深度理解的任务还是应该使用最强模型。可以这样按命令设置模型组/提交和/周报走本地模型/审查和/定位走云端模型。这样既控制了成本又保证了关键任务的质量。6.2 命令的自定义与团队模板沉淀团队使用的过程中命令会自然分化为“个人版”和“团队版”。我自己的实践是每个团队项目管理的关键命令从 10 个精简到 5 个——审查、定位、提交、周报、导读——剩下的归类为个人扩展命令。团队版本由一个人维护变更后通过 Git 合并到主干其他人git pull自动更新。另外可以考虑增加一个/模板命令它不做任何分析只是输出一组标准的 Markdown 模板包含代码 review 清单、项目交接文档、故障报告等。这个命令的价值不在于“智能”而在于统一团队的文档结构。时间长了团队产出的文档风格会非常一致后续检索和维护都省心很多。6.3 未来扩展定时任务与自动流程目前这套工作流包全部是“对话时触发”没有做到主动触发。后续可以考虑扩展的方向是把命令接入到 CI 流程中比如每次 MR 创建后自动触发/审查把审查结果写到 MR 评论里。也可以写一个定时任务每周五下午自动跑/周报把生成的内容推送到团队群。这些扩展的实现路径会复杂一些已经不是单纯的 Claude Code 范畴。但从实际收益看越往这个方向走效率提升越明显。代码质量检查从“人肉主动”变成“自动被动”工作流本身的维护成本也大幅下降。写在最后的实操体会这套 10 个中文命令组成的 Claude Code 工作流包用到现在大概三个月。我的体会是AI 编程工具的潜力很大程度上取决于你怎么包装它。同一套模型一个什么都不配置的人可能觉得它只是高级一点点的搜索引擎但一个把命令、权限、上下文管理都调好的人能把它用成真正意义上的“团队高级工程师”——能审查、能定位、能写文档、能出周报。如果你是刚接触 Claude Code我的建议特别简单今天先别写十个命令就写一个。挑你最痛的那个环节比如提交信息总是被吐槽那就先做一个/提交命令。跑通一次感受一下“输入两句话输出一段规范文案”的体验之后再逐步扩充。命令不是越多越好顺手才是硬道理。