1. 为什么要给 Claude Code 建一套模板很多人第一次用 Claude Code 的时候都会有一个类似的体验工具本身很强能读仓库、能改代码、能跑命令但每次让它做同一类事情都要重新输入一大堆指令。比如写提交信息、做代码审查、补单元测试每次说的描述方式稍不一样出来的结果水平就忽高忽低。我一开始也没当回事直到有一天发现自己在同一个项目里反复输入几乎是同一段话才意识到这些高频操作完全可以通过模板固化下来。所谓 claude-code-templates说白了就是把 Claude Code 的常用指令沉淀成可复用的模板文件让它按你设定的格式和流程去工作。Claude Code 本身并不叫模板它只是一个跑在终端里的 AI 编程助手。但通过 CLAUDE.md 和自定义命令配置你可以给它加装一套“行为规范”。这套规范就是模板。它的价值在于不用每次重新解释需求不用担心 Claude 忘记你规定的输出格式也不用在多个项目之间重复调教。你只需要配置一次之后无论在哪台机器、哪个仓库里只要喊一声斜杠命令它就能按照你指定的方式来干活。这个系列内容适合谁我觉得三类人最需要。第一类是在团队里用 Claude Code 做代码审查和 commit 规范化的人他们需要统一输出口径。第二类是个人项目很多、经常在仓库之间切换的开发者他们需要一个全局模板来保证体验一致。第三类是想把 Claude Code 当作团队“虚拟成员”来用的技术负责人模板能让 Claude 的输出风格和团队规范对齐。如果你是第一次听说模板这个概念也不用担心下文从设计思路到具体写法全部给你拆开讲清楚。2. 模板体系的整体设计思路2.1 先分清楚三类模板命令模板、项目规则模板、代码生成模板我用了大半年之后把 Claude Code 的模板分成三大类。第一类是命令模板也就是自定义 slash command通过在 CLAUDE.md 或者 CLI 配置目录里定义 /xxx 命令把一段复杂的 prompt 封装成一个简单的斜杠命令。这类模板适合“动作型”任务比如提交代码、审查 diff、生成测试、解释报错。第二类是项目规则模板通常就是一个项目的 CLAUDE.md 文件里面写清楚项目结构、代码风格、禁止事项、测试命令等。它不触发具体任务但每一次对话都会被加载相当于 Claude 在项目里的“入职手册”。第三类是代码生成模板它不是 Claude Code 的功能而是你写在模板里的“示范代码 约束条件”比如生成一个新的 API 接口时要求它遵循 controller-service-repository 分层并附上现有代码片段作为参照。这个分类有什么实际意义因为它决定了模板的存放位置和加载方式。命令模板放在 ~/.claude/commands/ 或项目 .claude/commands/ 目录下属于“按需加载”你输入 /test 才会生效。项目规则模板放在仓库根目录或子目录的 CLAUDE.md 里属于“常驻加载”每次启动或读取文件时都会带进上下文。代码生成模板严格来说是把“例子”写在指令里让它看着参照做不追求格式上的仪式感。如果不做这个区分很容易把什么都塞进 CLAUDE.md。我见过有人把一整个命令模板库都堆在 CLAUDE.md 里结果每次对话都要带着几千上万 token 的规则既浪费上下文又影响了 Claude 对当前任务的关注度。命令模板的好处就是按需加载平时不占上下文调用时才注入这样效率和成本都更可控。2.2 存放位置与加载优先级全局、项目、子目录Claude Code 的模板加载有一套默认的查找顺序这也是配置时最容易踩坑的地方。全局命令放在用户主目录下的 ~/.claude/commands/ 里对所有项目生效。项目级命令放在当前仓库的 .claude/commands/ 目录里只对这个仓库生效。还有一个容易被忽略的位置是 .claude/commands/ 下的子目录你可以用子目录给命令分组比如 .claude/commands/review/ 和 .claude/commands/commit/这样在终端里输入斜杠命令时会自动分组显示。从优先级来说项目级命令会覆盖全局命令。也就是说如果你在 ~/.claude/commands/ 里定义了名为 commit 的命令又在一个项目的 .claude/commands/ 里定义了同名命令那么在项目里执行 /commit 时使用的是项目版本。这个设计其实很实用因为不同团队对 commit 风格的规范可能不同。我就遇到过全局模板用的中文提交信息但某个仓库要求全英文只需要在那个仓库里放一个同名命令覆盖掉即可不必动全局配置。CLAUDE.md 的加载也有类似的层级项目根目录的 CLAUDE.md 优先级最高然后是子目录的 CLAUDE.md最后是用户目录下的全局 CLAUDE.md。不过我建议不要把太多东西放全局全局只放通用的编码偏好和禁止事项因为全局 CLAUDE.md 会影响所有项目模板里的每一句话都会被注入到上下文中。写得越多反而越稀释真正重要的指令。2.3 参数化让模板从“死模板”变成“活指令”模板最怕写死。一个命令如果只能做一件事那它很快就失去复用价值。我在设计模板时会刻意把可变部分抽出来用参数占位符表示。Claude Code 的命令模板支持用 $ARGUMENTS 来接收用户输入也支持 $1、$2 这种位置参数。比如一个 /commit 命令用户输入 /commit 修复登录页在移动端的跳转问题$ARGUMENTS 就会接收这段描述文字模板里再规定怎么利用这段描述去生成规范的提交信息。这里有个细节值得注意参数并不是简单地把用户输入拼进 prompt。你可以在模板里写“如果 $ARGUMENTS 为空请结合 git diff 自动推断变更内容如果 $ARGUMENTS 不为空以用户描述为准但需与 diff 进行交叉验证。”这样模板就具备了逻辑分支能力。虽然本质上还是在引导 Claude 的行为但体验上已经接近一个真正的小型程序了。还有一种参数化是“变量注入”比如用 $CLAUDE_PROJECT_DIR 获取项目路径或者用 $CLAUDE_SESSION_ID 区分会话。这些内置变量可以在模板中直接引用适合做路径相关的操作。不过别过度设计模板不是代码越简单越好维护。我见过有人给模板写了十几个变量和条件块最后 Claude 执行时反而迷路了因为精力全在解析模板逻辑上忽略了真正该干的事。3. 核心模板拆解与实操3.1 提交信息模板从源头规范 git commit提交信息是我最先做成模板的场景因为它足够高频而且规范性的收益立竿见影。一个团队如果每个人写 commit 的风格都不一样后续回溯问题会非常痛苦。我设计的 /commit 模板长这样仅供参考你完全可以根据团队规范改你是一个严格的 git 提交信息生成器。请根据以下信息生成符合 Conventional Commits 规范的提交信息。 要求 1. 类型必须使用 feat / fix / refactor / docs / test / chore / style 之一。 2. 作用域写在类型后面的括号中如 feat(login): 。 3. 描述简洁动词开头不超过 50 个字符。 4. 如果有破坏性变更必须在正文中标注 BREAKING CHANGE。 5. 如果 $ARGUMENTS 提供了描述优先使用描述内容否则根据 git diff 自行推断。 6. 只输出提交信息本体不要输出任何解释性文字。 当前 git diff --cached 的结果如下 git diff --cached 的输出这里有个关键点模板里如果没有自动注入 diff你需要让 Claude 自己运行 git diff 再生成。实测下来与其让 Claude 读取整个 diff 内容不如把 diff 输出截断到一个合理的长度比如只关注被暂存的文件和变更行。否则一个大型 MR 的 diff 动辄几千行塞进上下文既不经济也容易让 Claude 在无关细节里纠结。我的做法是在 prompt 中明确“只分析 git diff --cached --stat 和最近修改的函数级差异”这样既快又准确。3.2 代码审查模板不只看 bug更看设计代码审查模板可以说是团队协作的利器。以前你把一段 diff 扔给 Claude它会给你列一堆“看起来没问题”的空话。但有了模板约束它就能输出结构化的审查意见。我在 /review 命令里的配置分五个维度正确性、安全性、性能、可维护性、测试覆盖。每个维度下面有具体的检查清单比如正确性里要求找出“空指针、越界、资源未释放”等问题安全性里要求排查“注入、敏感信息泄露”等风险。模板里还要定义一个输出优先级的问题凡是能导致线上故障的问题必须放在最前面并且明确标注“严重”。凡是风格类建议统一归到“改进建议”不做强行要求。这样审查结果就分出了主次而不是一堆意见平铺开让人不知道先处理哪个。不过使用这个模板要注意一个边界Claude Code 的审查能力取决于它看到的代码上下文。只给它一段 diff 它只能做表面检查但如果给它相关的文件内容和依赖关系它就能发现跨文件的接口不匹配问题。我在模板里会带上“如需查看更多上下文请先运行 rg 搜索相关调用方再决定是否扩大分析范围”这个授权很重要否则它会为了省事只看局部。3.3 测试生成模板限定目标防止写出“假测试”测试是模板里最容易翻车的地方。Claude 在没有约束的情况下生成的测试经常是一些只测覆盖率不测逻辑的快照测试看着绿油油一片实际上什么也没验证。所以我在 /test 模板里加了很多限制条件你负责为指定的代码文件生成单元测试。 规则 1. 只使用项目中已有的测试框架和工具链不要引入新的依赖。 2. 测试用例必须覆盖正常输入、边界输入、异常输入、错误传播路径。 3. 每个测试用例必须有一个明确的断言禁止只做“无异常的烟囱测试”。 4. 对于外部 IO 或网络调用必须使用 mock不允许真实发起请求。 5. 给出测试文件所需的最小改动不要顺手重构被测代码。 6. 输出时先列出测试计划表格再输出代码。这个模板的效果非常明显。之前 Claude 生成的测试经常出现“测试了函数内部实现细节一重构就崩”的情况。加入“不要顺手重构被测代码”这条之后它就克制多了。另外“先列出测试计划表格再输出代码”这个点也强烈建议保留它能让 Claude 先想清楚测什么再动手写而不是边写边编造场景。3.4 代码解释模板给新人看的“口语化翻译官”代码解释不算高频但遇到难啃的老代码时一个稳定的解释格式能帮你节省大量时间。我的 /explain 模板会把输出固定为四段这段代码的职责、核心逻辑流程、关键数据结构与调用关系、潜在风险与改动建议。并且要求解释者以“面向刚接手项目的新人”的口吻来写尽量用类比说明少用抽象术语。这个模板写起来很简单但有一个容易被忽略的技巧在模板里加入“如果解释过程中发现代码问题请在最后以‘注意’开头的段落列出不要混入前面的流程描述”。这样解释和问题提报就分开了否则 Claude 容易在讲流程时突然插一句“这里有一个 bug”把整体逻辑扯断。处理完老代码之后这段“注意”内容还能顺手变成待办事项非常实用。3.5 命令模板中的高级变量与组合技巧除了上面几个常用命令模板还支持引用文件、拼接多个任务。比如你可以让 /docs 命令先读取某个模块的源码再调用 /explain 的输出格式生成文档。这在 Claude Code 里不需要写什么复杂的插件只要在 /docs 模板里这样写在开始之前先读取 src/services/userService.ts 文件。 然后按照以下步骤执行 1. 使用 /explain 中定义的思考流程分析该文件。 2. 将分析结果整理成 README 格式的文档。 3. 文档需要包含模块目标、公共方法、内部协作、异常处理说明。注意命令模板里不能真的调用另一个斜杠命令至少我用的版本里不支持这种语法。但你可以把 /explain 模板的内容复制进来或者用一个公共规则文件让 Claude 统一遵守。最推荐的做法是把共享要求写进 CLAUDE.md这样所有命令都能继承那些规则不必每个模板里都重复一遍。这就是组合的意义CLAUDE.md 是全局行为基线command 模板是具体任务的触发器两者各司其职组合使用。4. 模板的调试与常见问题4.1 模板不生效先检查文件名和路径我在配置模板时遇到最多的坑就是斜杠命令不出现。后来排查多了总结出几个高频原因。第一个是文件扩展名问题Claude Code 只认 markdown 文件扩展名写成 .txt 或 .md 的路径不对都可能导致不识别。第二个是目录层级问题全局命令放到项目目录里或者项目命令放到了子目录命令就不会被加载。第三个是命名冲突如果你定义了一个名为 review 的命令但某个内置命令也叫 review新命令可能会被忽略需要改个名字比如 code-review。遇到斜杠命令不生效最快的排查方法是先在项目里输入/看命令列表如果列表里没有你定义的命令再逐级检查目录。另外有时候修改模板不会立即生效需要重启当前会话或者重新加载项目这也是一个很容易忽视的点。我习惯在修改完模板后先执行一个简单命令验证比如 /help 看列表如果还是没有就检查是不是某个语法问题导致整个命令文件被解析失败。4.2 输出格式失控模板里设约束回复后加“刹车”模板写好了但 Claude 经常不按格式来怎么办我遇到过几次明明模板里写了“只输出 JSON”它偏偏给你输出一段解释外加 JSON。后来发现问题出在 prompt 的结尾没有闭合。在模板最后加上一句“现在开始生成最终输出。禁止输出任何与最终格式无关的内容”效果会好很多。这相当于给模型加了一个“刹车指令”让它结束内部思考直接进入交付阶段。还有一种格式化失控是 Claude 自主添加了 Markdown 表格或代码块导致你没法直接把输出喂给脚本。这种情况下除了在模板里反复强调格式还可以提供一个“输出示例”。比如要求生成 JSON 时模板中直接附上一段合法的 JSON 示例并注明“严格按照该结构输出”。大模型对示例的模仿能力比抽象约束要强得多这是一个不该省略的技巧。4.3 上下文太长的处理模板里明确信息边界和截断策略Claude Code 的上下文窗口不是无限的模板如果加载了太多代码或者让 Claude 重复读取大型文件很容易把上下文撑爆。我自己的经验是在模板里明确“只分析 diff 中新增和删除的行不要全文件阅读”以及“如果某个函数的实现超过 100 行只读取其主要分支和关键调用不要逐行展开”能让上下文消耗大幅下降。还有一种场景是命令模板里嵌入了大量项目规范导致每次执行命令时都要携带一份长文本。如果你的命令模板超过 3000 个 token建议重新审视内容。能写进 CLAUDE.md 的公共规则就不要塞进命令模板。命令模板应该是“轻量级触发器”不是“重型规则库”。遇到上下文溢出导致的答非所问多半就是这里出了问题。4.4 实测命令的运行权限需要谨慎授权的操作Claude Code 可以直接在终端里执行命令这是它强大的地方也是容易出事故的地方。模板里如果涉及 git push、rm、drop 这类高风险操作建议在命令模板中加一句“在执行前向用户确认并展示将要运行的命令全文”。我一开始在 /deploy 模板里写了自动编译并部署的步骤结果有一次它自作主张删了临时目录幸好是在测试环境。从那以后所有可能产生副作用的操作模板末尾都必须加确认步骤。如果你用的是自动审批模式那更要小心。模板中要尽可能限定命令的白名单范围比如只允许 npm run build、git add/commit其余一律人工确认。安全和效率的平衡点需要根据项目阶段不断调整。我的原则是新项目跑得勤先把确认关打开等模板稳定运行一周以上再逐步放开。5. 从模板到“个人工作流”的延伸5.1 不同语言和框架的模板差异同一个模板在不同技术栈里可能需要微调。比如写 Python 项目的 /test 模板默认用 pytest fixture而写 Node.js 项目的模板则更倾向于 jest mock。与其在一个通用模板里写“根据项目自动选择”不如按技术栈再细分子目录比如 .claude/commands/test/python/ 和 .claude/commands/test/node/。Claude Code 支持命令分组子目录这样在项目里执行 /test 时它会根据当前项目的环境自动匹配对应的模板吗实测下来并不一定需要你在模板里加一个前置判断“检测项目根目录是否存在 package.json如果存在按照 Node 模板执行否则按照 Python 模板执行。”这类分支逻辑实际上是把模板当成了“可编程 prompt”。虽然它不是一个真正的程序但通过让 Claude 先做环境探测再决定行为可以解决很多多项目复用时的适配问题。耗时也就多几行 prompt却能让一套模板横跨多个项目。5.2 在团队中共享模板的最佳姿势模板做出来之后就面临共享问题。如果你在团队里负责维护 claude-code-templates建议把模板目录直接作为仓库的一个子目录提交到代码库比如 .claude/commands/ 随项目一起入库。这样所有克隆该仓库的人都会自动得到相同的命令体验。全局模板则不适合入库因为那是个人偏好每个人的全局配置应该独立维护。当然有些团队会把模板单独抽成一个公共仓库然后用 git submodule 或符号链接挂到各个项目里。这是一个进阶玩法好处是更新一次模板所有项目同步生效坏处是增加管理成本如果项目不主动拉取最新 commit反而会出现“命令版本不一致”的问题。个人项目阶段不必上这种复杂度等团队确实感受到“模板复制粘贴”带来的维护压力时再抽公共仓库也不迟。5.3 用模板反推自己的低效操作我发现一个很有意思的副作用整理模板的过程会逼着你把自己平时反复做的事情列一遍清单。每一次模板的创建都是对你工作流的一次抽象。你说不清怎么让 Claude 帮你做某件事说明你自己对这件事的流程也未必想明白了。比如以前我写提交信息是全凭感觉做了模板之后反倒把团队规范里的 type 和 scope 梳理了一遍也对“结构清晰的提交信息到底长什么样”有了更明确的定义。这套方法也能用在写文档、做复盘、排优先级上。你可以为周报生成建一个模板让 Claude 根据这一周的 commit 记录和 MR 汇总生成结构化周报草稿。也可以为开工前的任务拆解建一个模板让它按照“目标—现状—阻碍—下一步”的结构整理你的想法。Claude Code 模板本质上就是一个思维脚手架它不只是在解放你的手也是在帮你把散落的经验变成可复用的资产。5.4 模板代码也要做版本管理最后一个建议模板本身要纳入版本管理。我在 .claude/ 目录下专门放了一个 README说明每个命令的用途、使用场景、修改记录。每当我调整 /review 的检查维度或者修改 /commit 的格式规范我都会顺手更新 README 的日志。这样做有两个好处一是过后回溯时能知道这个模板为什么变成现在这样二是当你把模板分享给别人的时候对方不用去猜你的设计意图。模板不是一次写好的它需要跟着项目和团队一起迭代。刚开始可以从最简单的 /commit 做起跑两周后观察 outputs 是否稳定再慢慢加更复杂的命令。等到命令多了自然会形成一套适合自己节奏的 claude-code-templates。我的核心心法是不要追求一步到位让模板从单一命令长成完整体系这个生长过程本身就是你和 AI 助手磨合出默契的过程。根据我个人的实践模板带来的不只是一点点效率提升更重要的是那种“每次打开终端都知道这个 AI 助手会按我的习惯来”的确定感。如果你也常年在各种命令行任务里手动喂指令不妨从今天起把第一个 /commit 模板写出来然后把以后每个重复动作都考虑沉淀成一条斜杠命令。用不了几周你会有完全不同的 Claude Code 使用体验。