1. 从每次手写长指令到模板资产化这个项目到底解决了什么先说我自己的处境。我在团队里用 Claude Code 做日常编码接近一年最初的习惯是每个任务临时打一大段 Prompt比如帮我看一下这个文件的问题并修复写个测试按规范生成 commit message。一开始还好后来发现同一个仓库里反复出现的任务其实就那几类而我在每次开始前输入的引导语有七八成是重复的。真正耗时的地方不是让模型跑代码而是我自己的废话占了上下文输出还经常跑偏。所以我动手整理了这套claude-code-templates。目的很直接把高频任务的指令沉淀成固定模板放进工程仓库让每一次调用都有稳定的角色设定、上下文注入、约束条件和输出格式。这里要澄清一个常见误区——模板不是提示词大全不是把上百条 Prompt 堆在一个 markdown 文件里就完事。真正的模板本质上是把一个人对代码库的理解、编码习惯、避坑经验固化成可复用、可演进、可交给他人的工程资产。模板化之后的收益我实测下来有三点很明确输出稳定性。同一个任务不管谁来用、什么时候用模型的输出结构基本一致。比如代码审查之前十次有十种排版现在统一按严重程度排序文件定位修改建议输出review 效率提高了一截。上下文质量。模板里预置了项目规范、相关文件引用、历史约定模型不需要靠猜第一次输出就接近可用状态。知识传递。团队新成员上手时看一遍模板就懂了这个项目的代码习惯和常见坑相当于把一个老开发的经验写进了文件。这套做法不只适用于编码凡是需要重复向模型描述你是谁、要干什么、遵守什么规则、输出成什么样的场景都可以模板化。下面我会从载体、设计方法、可抄作业的模板实例到工程化细节和踩坑清单完整拆一遍。2. 两个核心载体CLAUDE.md 的人格设定与斜杠命令的技能包Claude Code 的模板能力我理解下来其实就是靠两个东西落地一个是CLAUDE.md一个是自定义斜杠命令Slash Commands。两者互相配合搞懂边界之后模板体系才算立住。2.1 CLAUDE.md项目级的长期记忆与编码锚点CLAUDE.md是放在项目根目录也可以按需放在子目录的说明文件Claude Code 在执行任务时会自动读取相当于给模型一份关于这个项目的长期记忆。你可以在这里写项目技术栈、目录结构、启动命令、编码规范、常用脚本、禁止事项。我常用的写法是这样# 项目概况 - 基于 TypeScript 的 Node.js 服务使用 pnpm 管理依赖 - 采用 monorepo 结构核心业务代码在 packages/core - 运行测试pnpm test --filter core # 编码规范 - 缩进使用 2 空格不写分号 - 组件一律函数式声明禁止使用 class 组件 - 接口返回统一包一层 { code, data, message } # 常见命令 - 本地开发pnpm start - 构建pnpm build这份文件建议保持在 3060 行的量级太长模型会稀释注意力。它是项目级模板的地基所有斜杠命令都跑在它所定义的上下文之上。比如你在命令里说按项目规范写代码模型就会去CLAUDE.md里找规范不需要命令文件里再重复一遍技术栈。2.2 Slash Commands把高频任务做成技能包斜杠命令是 Claude Code 里的自定义指令默认放在.claude/commands/目录下每个命令对应一个 markdown 文件。你在交互界面里输入/bug-fix、/code-review这类斜杠命令模型就会按照文件里写好的指令执行。一个典型命令文件长这样--- description: 定位并修复代码缺陷 argument-hint: 文件路径或问题描述 --- 你是一名资深后端工程师请修复用户描述的问题。 问题描述{{$ARGUMENTS}}这里的$ARGUMENTS是参数占位符你在命令后面输入的参数会自动填充进去。命令文件的正文才是真正的指令模板本身frontmatter 里的description和argument-hint用于在命令列表中展示让调用者知道这个命令是干什么的、参数怎么传。我把 CLAUDE.md 理解成项目人格设定斜杠命令理解成高频技能包。人格设定负责全局一致技能包负责专项任务。两者边界如果不分清就会出现两种情况要么命令文件把项目背景重复写八遍浪费 token 不说还容易跟CLAUDE.md冲突要么CLAUDE.md里塞满了各种任务流程导致每次普通对话也背着沉重的上下文。2.3 目录组织与命名习惯在确定建立模板库之后我建议一上来就规划好结构.claude/ commands/ bug-fix.md code-review.md gen-tests.md commit-msg.md explain.md命令文件名就是斜杠命令名划线命名更清晰不要用空格。description这一项一定要写具体因为团队其他人要能从命令列表里一眼看出用途。另外命令文件可以引用项目里的其他文件后面我会专门讲怎么用文件引用做上下文注入。3. 模板设计方法论五要素拆解与参数注入很多模板不好用的原因不是模型不行而是指令本身写得不行。我拆过自己和同事写的各种模板发现高质量模板基本都包含五个要素角色、上下文、任务、约束、输出格式。一套模板只要把这五件事写清楚质量就有八成保证了。3.1 五要素模板的完整样例下面是我设计模板时最常用的骨架你可以直接参考它的结构--- description: 用一句话说清楚这个命令做什么 argument-hint: 提示用户该传什么参数 --- 角色你是一名具备 X 年经验、熟悉 Y 技术的资深工程师。/角色 上下文项目背景、目标文件、相关规范必要的时候用 引用具体文件。/上下文 任务请完成以下事项 1. 先定位问题 2. 再输出修改方案 /任务 约束 - 不要修改与本次任务无关的代码 - 不确定的信息明确说明不要编造 /约束 输出格式 请按以下结构输出 ## 问题分析 ## 修改方案 ## 验证步骤 /输出格式你会发现这五要素其实就是回答模型的五个问题你是谁你在什么情境下你要做什么有什么不能做做完给我什么格式的东西模型的所有幻觉、跑偏、格式混乱几乎都能追溯到这五件事里的某一件没写清楚。3.2 参数注入的三种方式模板不能总是无参函数实际使用中需要针对不同文件、不同需求做变化。参数注入我实测常用三种方式命令行参数直接写在命令后面通过{{$ARGUMENTS}}注入。适合传文件名、函数名、关键词。比如/explain src/utils/date.ts。文件引用在命令文件里用路径引用项目文件Claude Code 会把文件内容读进来作为上下文。比如src/services/userService.ts比让用户手动复制粘贴代码方便得多。环境信息通过CLAUDE.md或系统级配置提供的项目信息比如技术栈、目录结构。这部分不需要每次传模型会自动携带。我用得最频繁的是前两种。比如gen-tests模板用户只需传一个文件路径模板内部用把源码引进来再让模型基于源码生成测试。这样命令是固定的输入参数却非常灵活。3.3 为什么短指令、长上下文是最优解这是我从多次实践中总结出来的一个重要原则模板里尽量少写你应该如何思考这种大道理把空间留给真实的上下文。举个例子同样是写测试模板差的版本是请认真阅读上面的代码分析函数逻辑考虑到各种边界情况包括空值、非法输入、大字段、超时……然后写出高质量的单元测试。好的版本是目标文件src/utils/format.ts 请针对该文件的每个导出函数生成单元测试。测试框架为 Vitest。信息密度完全不同。前者大量内容是在叮嘱模型这些词对模型没有实际指导意义反而稀释真正的指令后者把对象、框架、动作全部钉死模型可以直接开工。CLAUDE.md里已经写过测试框架那么模板里甚至可以不写测试框架为 Vitest上下文会自动带上。模板文件应该保持精简把上下文从项目文件里拉进来而不是把所有背景塞进命令文件里。4. 五个可直接照抄的实战模板下面这五个模板是我目前项目里每天都在用的全部经过多轮迭代。你可以直接复制到.claude/commands/目录下按需微调。4.1 模板一bug-fix让模型先复现再动手--- description: 定位并修复指定代码缺陷输出根因分析和修改方案 argument-hint: 文件路径或简要问题描述多个参数用空格分隔 --- 你是一名资深软件工程师擅长通过代码审查和日志分析定位问题。 问题描述{{$ARGUMENTS}} 请严格按以下步骤执行 1. 先阅读相关代码复现问题逻辑不要急于修改 2. 定位根因指出问题所在的文件、函数、具体行号 3. 给出修复方案说明修改思路以及影响范围 4. 修改代码输出完整 diff 或修改后的代码块 约束 - 区分已确认的根因与可能的猜测不要含糊 - 如果问题描述中缺少复现信息先列出你还需要的三个关键信息 - 不要修改与本问题无关的代码 输出格式 ## 问题复现路径 ## 根因分析 ## 修改方案 ## 修改后的代码 ## 验证建议这个模板的核心是第一步先复现。模型最常见的毛病是一上来就猜一个原因然后对着那个猜测改代码最后原问题没解决。我在模板里强制它先列出复现路径既是为了让模型自己捋清逻辑也是为了让使用模板的人能判断它的理解是否正确。4.2 模板二code-review审查意见要可执行不要正确的废话--- description: 对指定文件执行结构化代码审查输出分级问题清单 argument-hint: 文件路径 --- 你是一名严格的代码审查者熟悉本项目的开发规范参考 CLAUDE.md。 审查对象{{$ARGUMENTS}} 请按以下结构输出审查意见 ## 审查概览 一句话概括本次审查范围和代码整体质量。 ## 问题清单 按严重程度从高到低排列每个问题包含 - 严重级别P0可导致故障/安全风险、P1逻辑缺陷、P2可维护性问题 - 位置文件路径 函数名/行号 - 问题描述说明为什么这是一个问题 - 修复建议给出具体修改思路不要写建议优化这种空话 - 是否阻塞合并是 / 否 ## 亮点 如果代码中有值得肯定的设计列出来。 约束 - 不要吹毛求疵不要为了凑数量列问题 - 如果某处只是为了风格偏好而非逻辑问题明确标注为风格建议 - 涉及依赖安全、异常捕获、状态变更的内容要特别标注用过之后最明显的感觉是P0/P1/P2的分级让团队 review 效率大幅提升大家只用看 P0 和 P1 就能决定是否合并。模板里特别写了一条不要为了凑数量列问题因为模型默认会自动生成一堆无伤大雅的小毛病没有这条约束审查清单会非常吵。4.3 模板三gen-tests先列行为矩阵再写测试代码--- description: 基于源码生成单元测试输出测试矩阵和可运行代码 argument-hint: 文件路径 --- 你是一名测试工程师擅长编写边界充分的单元测试。 目标文件{{$ARGUMENTS}} 请先用 引用目标文件阅读源码后按以下步骤执行 1. 列出测试用例矩阵每个导出函数对应的用例名称、输入、预期行为 2. 覆盖要求正常路径、边界值、空值/undefined、异常输入、大字段 3. 依据测试矩阵生成测试代码使用项目已有测试框架 4. 输出代码前说明 mock 了哪些外部依赖及原因 约束 - 不要生成只能自我证明的测试比如 mock 了被测函数内部实现 - 不要为了覆盖率强行造用例 - 外部服务、网络请求必须 mock纯函数不做无谓 mock 输出格式 ## 测试用例矩阵 ## 测试代码 ## mock 说明 ## 建议补充的集成用例为什么先要测试用例矩阵因为矩阵是给人的评审依据模型列矩阵时如果对函数理解错了人的评审成本比读完一堆跑不动的测试代码再发现方向错了低得多。矩阵确认没问题测试代码基本一次成型。我实测下来这个模板把从零写单测从半小时压缩到五分钟而且质量比我手写还整齐。4.4 模板四commit-msg从 git diff 生成规范提交信息--- description: 根据暂存区或指定 diff 生成符合规范的 commit message argument-hint: 可传可选背景说明 --- 你是一名熟悉 Conventional Commits 规范的开发者。 请先执行 git diff --cached 查看暂存区改动也读取一下最近五条提交历史来参考项目实际的提交风格。 任务 1. 概括本次改动的主题 2. 生成一条 commit message格式type(scope): subject 3. type 限定为 feat / fix / docs / refactor / test / chore / perf 4. subject 控制在 50 字以内正文可以描述动机 约束 - 不要添加冒号、引号等与提交无关的装饰 - 如果暂存区为空明确提示并停止 - 不确定的改动意图列出两种可能的提交信息让用户选择 输出 只输出 commit message 本体不要输出解释。这个模板看起来简单实际很有讲究。很多人让模型生成 commit message得到的是一堆优化了代码结构并提升了可维护性的空话。所以我在模板里加了两个关键约束让它参考最近五条提交历史模仿团队真实风格以及只输出 commit message 本体防止模型废话连篇。实际体验非常好commit 质量肉眼可见地提升历史看起来整齐多了。4.5 模板五explain陌生代码的阅读路径--- description: 解释指定代码的执行逻辑与设计意图 argument-hint: 文件路径可附带具体函数名 --- 你是一名代码讲解专家擅长把复杂逻辑讲清楚。 目标文件{{$ARGUMENTS}} 请按以下结构输出 ## 一句话概述 ## 执行流程 从入口开始按调用顺序解释主要执行路径可以标注关键分支条件 ## 关键数据结构 涉及到的对象、状态、缓存等 ## 调用关系 被谁调用、调用了谁用列表说明 ## 设计意图 这个模块为什么这样设计解决什么问题 ## 潜在风险点 状态变更、异常处理、性能隐患explain是我给新人准备的模板。团队里新人接手旧代码时往往不知道从何看起。以前是我陪着他一行行讲现在他把文件路径丢给这个模板先拿到一套结构化的解释再带着疑问来问我效率完全不同。注意模板里我用了潜在风险点而不是改进建议因为对于解释场景识别风险比给建议重要新人不需要一上来就想着改代码。5. 模板工程化的四个细节上下文、约束、变量与质量兜底模板能用只是第一步要稳定、可维护还得把这四个工程化细节处理到位。这些都是我在多轮迭代中慢慢补出来的。5.1 用 文件引用注入上下文而不是让用户粘贴代码命令文件里出现src/utils/format.tsClaude Code 会读取该文件内容并注入上下文。这是模板最实用的能力。它意味着用户只需要传一个路径不需要把代码复制进参数模型读到的文件内容比用户粘贴的更完整不会因为粘贴截断而丢上下文模板本身保持干净不用内嵌大段代码文件引用还能组合多个文件。比如做代码审查时引用源码和对应的测试文件src/utils/format.ts tests/format.spec.ts。同一个任务模型能同时看到实现和用例审查质量比只看源码好很多。我在bug-fix和code-review模板里都推荐用户尽量传文件路径而非问题描述就是这个原因。5.2 用 frontmatter 维护命令的元数据每个命令文件开头的---部分是 YAML frontmatter里面可以写这个命令的元信息。我至少会维护两个字段字段作用我的建议description在命令列表中展示的说明一句话说清这个命令干什么不要超过20字argument-hint提示用户传入什么参数写明参数格式比如文件路径或问题描述可用多个词这两个字段不写命令也能用但团队其他人根本无法从命令列表里判断该选哪个、参数怎么传。我经历过这种情况同事把/bt当 bug 修复命令用结果我那个bt其实是build type的缩写。所以description一定要具体命名尽量用完整单词。5.3 防幻觉约束把区分事实与推测写进指令模板工程化里最重要的一条是防幻觉。我的做法是在模板里显式声明某些输出必须区分已确认的事实基于上下文的合理推断需要你进一步确认的部分。典型语句如果某个信息不能从上下文确认明确标注需要确认不要自行假设。这句话看起来简单实际能救回很多错误。比如 bug 修复时模型会把一个没依据的猜测说得斩钉截铁有了这条约束它会主动列出还需要用户提供哪些信息。发布、迁移、删除操作这类高风险任务我还会额外加一句涉及破坏性变更时先列出变更清单并等待确认再继续执行。5.4 输出即产物把验收清单写进模板最后一个工程化细节是让模板自带验收标准。很多模板只写了做什么没写做完怎么判断对不对。我在程序生成类和重构类模板里都会加一段验收清单输出前请自查 - [ ] 代码可以独立运行且无编译错误 - [ ] 主流程和边界场景均有处理 - [ ] 没有修改无关代码 - [ ] 涉及外部依赖时已说明 mock 原因这段自查清单看起来是给模型看的实际上是给人看的。模型输出之前按照清单逐项检查能显著减少代码看起来完整但根本跑不起来的情况。我见过不少模板生成的代码凡是加了自查项的可直接用的比例明显更高。6. 团队模板沉淀与个人避坑实录模板这种东西单个开发者自己用是效率工具团队一起用才是资产。最后这部分聊聊怎么把模板在团队里落地以及我在迭代过程中踩过的坑。6.1 团队统一模板的三个落地原则模板进版本库。.claude/目录跟着代码仓库走新成员 clone 下来就能用。不要放在个人电脑的零散文件夹里那样根本沉淀不下来。模板变更走 PR 流程review 模板的人同时也是模板的使用者。先固定两个命令再拓展。团队刚开始引入时不要一次性铺开十个命令。我会建议先固定code-review和commit-msg这两个因为它们几乎每个项目都通用。跑两周收集反馈再慢慢添加bug-fix、gen-tests这些。一次铺开太多大家对模板质量没信心后面就没人用了。模板要有 owner。每个模板指定一个人维护。模板质量问题、输出结构变化由 owner 收集意见迭代。没有 owner 的模板很快就会烂掉。我在团队里的真实体会是模板机制推行最难的从来不是写文件而是让大家相信模型输出稳定可预期。前两次如果输出格式变动很大信任就崩了。所以早期固定一套结构非常重要宁可内容少一点结构不要变来变去。6.2 踩坑清单这些错误我全部犯过错误一指令太宽泛。我最开始写的 bug 模板是请修复代码中的问题没有任何约束。模型输出了一堆无关紧要的优化真正的 bug 没找到。后来加上先复现、再定位根因、给行号、区分事实与猜测才变得可用。错误二没有输出格式约束。这是所有模板最容易忽略的一点。同一份 code-review第一次输出用表格第二次用列表第三次用段落直接导致无法用任何自动化脚本或人工习惯去消费它。现在我的每个模板都强制写清输出格式小节格式一旦稳定后续解析和处理都方便。错误三上下文不足就硬让模型干活。有一段时间我的gen-tests模板只让模型写测试不引用源码。模型只能靠记忆里模糊的项目知识去猜函数签名生成的测试一半跑不起来。改成必须用引用目标文件后问题才彻底解决。错误四模板里堆积太多正确的废话。你是一个专业且富有经验的开发者这种话在十个模板里出现把真正有用的约束淹没了。我现在写模板的原则是每个指令词都必须服务于任务的某一环不能只为了显得专业而存在。6.3 一个提高模板迭代质量的小习惯最后分享一个我坚持到现在的小习惯定期统计模板的失败率。我的做法是在每个模板的description里不做文章而是每两周围绕常用模板做一次回查把输出不可用的例子收集起来看是哪个环节出了问题。修复模板本质上是修复人类描述需求的精度而不是修复模型。这个视角很重要。如果让我给还没开始做模板的人一个建议那就是从commit-msg这种小命令开始先感受一下固定指令带来稳定输出的体验再逐步构建自己的模板体系。模板库不需要一次建成它会随着你对项目、对工具的认知一起演进。