如果你已经用 Claude Code 写过一段时间代码大概率会有这种感觉同样一句话上午问它和下午问它输出风格能差出两个版本。最离谱的一次我让它重构一个工具函数它顺手把我整个文件都格式化了一遍diff 里几百行全是单双引号和换行符的变动真正的逻辑改动不到三行。这不是模型退化了而是提示词太随意。对话里只写了一句“帮我重构一下 utils/format.ts”没有给背景、没有给范围、没有告诉它保持什么、也没有要求输出什么格式。于是 AI 只能根据自己的“理解”自由发挥——它觉得格式化也算优化觉得改个命名也合理。所以问题不在 AI而在我们的输入太模糊。后来我开始整理 claude-code-templates一套面向 Claude Code 的提示词和工作流模板库。说白了就是把高频的开发动作代码审查、功能开发、重构、写测试、编文档做成固定格式的文本模板需要的时候直接喂给 Claude Code让它按流程执行。这套东西解决的是三个问题输出不稳定、上下文浪费、团队协作时每个人跟 AI 对话的水平参差不齐。适合正在用 Claude Code 做实际开发的工程师也适合想把 AI 辅助开发的打法固化下来的技术团队。1. 为什么要给 Claude Code 做模板先解决“每次对话都从零开始”的痛1.1 没有模板时的真实状态没有模板的时候我每天要花大量时间写一次性提示词描述函数边界、贴代码片段、反复纠正输出格式。写得好那一次对话效率高写得不好对话来回拉扯上下文窗口被无效内容占满。更麻烦的是同一个团队里有人会把需求讲得很细有人只会丢一句话出来的代码质量完全不可控。我印象最深的一次是让 Claude Code 优化一个列表分页逻辑。我原话基本是“这个分页性能不行优化一下”。它在没有看到调用方的情况下直接改成了游标分页还顺带重构了控制器层的入参。逻辑上是进步了但调用方全部报错半个下午都在回滚。这个例子特别典型当提示词里缺少数量的约束条件时模型就会用自己认为“更好的方案”去替代现有方案而不是在方案约束范围内做改进。后来我把这个场景写进模板先要求 AI 读取调用方代码再要求它列出当前实现的问题点最后要求它在不改变接口签名的前提下给出优化方案。加了这几步之后同样的任务再没出过那种破坏性改动。这件事让我确定了模板的价值不是让 AI 更聪明而是让它更听话按既定轨道走。1.2 模板真正解决的三个问题第一个收益是稳定性。以前同一个任务每次写不同的提示词模型输出如同开盲盒模板把约束条件固定下来之后虽然不能保证 100% 一致但至少风格、流程、输出格式保持在可控范围。代码审查不会再一会儿朝我抛二十条建议一会儿只回一句“看起来没问题”。第二个收益是省上下文。模板里已经写清了背景、步骤和验收标准对话中就不用反复补充说明和纠正偏差长对话里的额度可以留给更关键的业务逻辑。过去我为了讲清一个重构需求经常要贴三个文件进来再用四轮对话解释现状差异。现在模板会直接指挥 AI 自己读文件、自己对比、自己汇报我在对话里只需要说“按重构模板处理”加上目标路径。第三个收益是能力复制。一个资深工程师调教好的模板新人拿过来就能产出接近同水平的提示词这个在团队里价值特别高。AI 编程工具正在把编码能力摊平但真正拉开差距的是谁更能提出好问题、设计更清晰的验收条件。模板库等于把个人经验变成了组织资产新人不用靠几次失败对话去积累教训。1.3 一个容易被误解的点模板不是限制发挥有人一听“模板”就觉得会让 AI 变成复读机每次都输出一个模子。我的体会恰恰相反模板锁死的是流程和边界不是锁死思路。比如代码审查模板要求 AI 按“严重程度”输出问题它依然要自己判断代码哪里有隐患、哪里性能差只是判断完之后要放到统一的格式里。这就好比你在公司里给团队定流程提测前必须回归测试、上线前必须看日志。流程本身不限制工程师的能力反而保证每件事不会被遗漏。模板给 AI 带来的也是类似的确定感在大方向明确的前提下细节由它自己灵活处理。我见过一个很典型的输出对比同样一段代码审查没有模板的 AI 会花很长篇幅夸代码写得好然后给三条无关痛痒的建议有模板的 AI 则会直接列出风险项并附上复现路径。后者才是一个合格审查者该有的样子。2. claude-code-templates 的整体设计思路2.1 模板的五段式骨架我写了十几个模板之后发现面向代码任务的模板可以抽象成一个五段式骨架目标、输入、步骤、验收、输出。不管任务是写功能、修 Bug 还是写测试这五段都能套上只是内容侧重不同。先看“目标”。目标要写得像工程任务书里的验收标准而不是一句口号。比如不要把目标写成“让用户登录更安全”而要写成“登录接口需要增加暴力破解防护失败五次后锁定账号 30 分钟并记录日志”。这个细节很重要因为 AI 判断“完成”的依据就是目标边界。目标越模糊它越容易自我满足然后懵懵懂懂地认为任务已经做完了。然后是“输入”。输入段要告诉模板从哪里获取信息涉及哪些文件、哪些上下文、使用什么语言和框架。这里可以写路径也可以写“先读取 src/controllers/auth.ts 再开始分析”。我发现让 AI 先读文件再执行比把代码粘进提示词里更靠谱因为大模型对完整文件的理解远好于对粘贴片段的片段式理解。粘贴代码经常丢失上下文而读文件能让模型看到导入关系、调用方和类型定义。接下来是“步骤”。步骤是把任务拆成子操作每一步设计一个明确的产出物。典型的一套流程是先读代码确认现状再写实现计划计划经过用户确认后再动文件最后跑测试验证。步骤的意义不在于让 AI 一板一眼而在于给它一个“施工顺序”避免它跳过分析直接改代码。这个部分相当重要没有步骤约束时模型的默认行为是尽快完成输出几乎不会停下来确认方向正确。“验收”段是模板里最容易被忽略的部分。它定义每一步做完之后怎么判断结果是对的。比如“重构完成后原有单元测试必须全部通过”“日志中不能出现敏感信息”。验收条件写得好模板就像装了检查点AI 自己就会在输出前做一轮检查省掉我们人工复核的很多时间。很多模型输出看着积极但经不起验收缺少明确验收标准是主要原因。最后是“输出”。输出段约束最终交付物的格式。同样是写一段代码是只输出 diff还是同时给出风险说明是直接在文件里改完还是先给方案这都需要在模板里讲清楚。输出写得越明确后续人机协作的摩擦就越少。我给大多数模板都定了输出格式有的要求 JSON有的要求 Markdown 表格有的要求先给摘要再给细节效果都明显好于“你把结果告诉我”这种模糊指令。2.2 按照 Claude Code 的能力边界设计流程模板设计不能凭空想必须贴合 Claude Code 的实际能力。它不是一个只能聊天的对话窗口而是一个能直接操作代码仓库的编程助手可以读取文件、编辑多个文件、在终端里执行命令还能运行测试并读取结果。所以我在模板里会刻意利用这套能力。比如代码审查模板里我会写上“先用 grep 搜索 TODO/FIXME 标记再逐个阅读相关函数”因为用搜索定位再精读比让 AI 从头到尾扫一遍文件高效得多。又比如重构模板里写上“改完一段后立刻运行对应的单元测试测试通过再继续下一段”这正是把终端执行能力嵌进了流程。对比来看只把模板当“提示词”用的人通常会在对话框里贴大量代码和解释而把模板当“工作流”用的人会让 AI 自己先去仓库里收集信息。前者是让 AI 当顾问后者是让 AI 当执行者。两者效果差距很大我建议一开始就把重心放在后者。原因很简单当 AI 能自己读代码、自己跑测试时人工只需要做决策工作量会大幅下降。2.3 目录结构与命名规范我的模板库文件结构大概是这样的templates/ ├── README.md ├── code-review.md ├── feature-dev.md ├── refactor.md ├── bug-fix.md ├── test-gen.md ├── docs-writer.md └── git-commit-msg.md命名用 kebab-case一眼能看出来模板用途。每个文件内部我习惯在开头写两行元信息用法摘要和适用场景。比如 code-review.md 的第一行会写“适用于提交 Merge Request 之前的代码审查重点排查安全、性能、边界条件”。README 是模板库的索引页。我会把每个模板的使用场景、调用方式、依赖条件写清楚这样过两周回来改模板时不用挨个打开文件回忆当初的设计意图。这套目录本身就是一个可以直接 git 管理的资产放到团队仓库里每个成员都能看到最新版本。我最初没有维护 README一周后自己都忘了两个模板之间有什么区别后才补上索引现在这份文档成了我逢人必推配置文件。3. 四个高频模板的实际拆解3.1 代码审查模板如何让 AI 只挑真问题而不是刷屏式建议代码审查是我认为投入产出比最高的模板。原因很简单日常开发里最耗时的不是写代码是 review。让 AI 先审一遍人类再针对性复核效率能提不少。但如果不加约束AI 的审查结果会非常灾难每行代码它都能提一句“建议增加空指针判断”“可以优化命名”全是正确废话。我在模板里加入了一个关键约束问题必须按严重程度分级并且每条问题必须写明触发路径。下面是我用的核心片段请对本次变更执行代码审查输出 JSON 格式的结果 { critical: [{file: , line: , issue: , trigger: }], warning: [{file: , line: , issue: , trigger: }], suggestion: [{file: , line: , issue: }] } 规则 - critical 必须是会产生线上故障、安全漏洞或数据丢失的问题 - warning 是潜在风险例如边界条件未处理、并发访问无保护 - suggestion 只是风格或重构偏好且最多不写超过五条 - 每条 critical/warning 必须给出具体的触发场景不能只写结论。这个模板设计背后的逻辑是让 AI 在输出前先过一道“自我质疑”关卡。它想写一条 warning就必须先回答“这个问题在什么输入下会真的爆发”。很多表面上的问题在这一步就被过滤掉了。而且 JSON 格式让结果可以直接被脚本消费也可以人工快速扫读。用下来最明显的感受是刷屏式建议少了很多真正的安全问题反而会被它捞出来。有一次它指出“第三方回调地址没做域名白名单校验”这个问题在人工 review 时确实被漏掉了。审查模板最终能做到的是让 AI 从“看起来在认真看代码”变成“确实在按风险优先级看代码”。3.2 新功能开发模板先出方案确认后再动手新功能开发最容易翻车的地方是 AI 理解错了需求还闷头写。我见过它把“支持批量导入”理解成“把导入按钮做成多选”方向偏了之后整个实现都被推翻。后来我给 feature-dev 模板加了强制流程第一步只做方案代码一行都不准写。模板的步骤段大概是这样执行步骤 1. 读取项目 README、package.json 和 src/ 目录结构确认技术栈 2. 分析新增功能需要改动的文件清单 3. 输出实现方案包含数据流、接口变更、涉及文件列表、风险点 4. 等待我确认方案后再开始编写代码 5. 实现完成后运行新增和相关的全部测试并汇报结果。这套流程的核心价值是把 AI 从“直接写代码”拉回到“先对齐认知”。它输出的方案就像程序员写代码前的设计文档哪怕方案不完全对纠错成本也比推倒一整份代码低得多。有一回我要加一个导出 CSV 的功能AI 在方案里建议用异步任务生成文件而不是同步接口这个设计就是对的比我自己拍脑袋更稳。第三个注意点是模板里要明确告诉 AI“方案被拒绝时可以继续修改而不是直接开写”。因为模型天生倾向于完成任务不给这句约束它可能刚输出完方案就顺手把代码写了步骤控制就失效了。这个细节我是在踩坑之后补上的一开始模板里只写了“先输出方案”结果它真的把方案和实现代码一起给了等于步骤白设。3.3 重构模板锁死行为小步前进重构是另一个高风险任务。AI 非常容易在重构时夹带“私货”顺手改格式、顺手重命名变量、顺手调整顺序。这些改动看起来无伤大雅但在 diff review 时会变成噩梦——改动面越大越难确认行为是否保持一致。我用的重构模板会先声明三条铁律铁律 - 不改变任何对外接口的名称、签名和行为 - 不修改与重构无关的代码格式、注释和命名 - 每次只重构一个函数或一个模块完成后立即运行相关测试并汇报。实现步骤里也加入了“先建立安全网”的要求动手之前先确认目标文件已有测试覆盖如果测试缺失先补充关键断言再开始重构。这里的原因很直接没有测试兜底的重构本质上就是蒙眼换零件。一旦行为偏移你连哪个环节出了问题都找不到。这项模板最大的收获是减少惊吓。以前让 AI 重构它偶尔会给我“惊喜”比如把变量名改成一个完全不同的词或者把模块内部状态写成闭包。现在铁律挂在前面它至少会克制很多。即使偶尔仍出现越界修改因为每次只动一个函数diff 看下来很快就能定位问题。重构这类任务尤其适合“小步快跑”模式模板的职责就是把这个节奏固定住。3.4 测试生成模板先列覆盖矩阵再写断言AI 写测试有个通病太喜欢写“快乐路径”。正正常常的输入、正正常常的断言、全跑通但假数据场景、超时场景、并发场景一个都没有。这种测试写出来覆盖率数字很好看实际价值不大。所以我给 test-gen 模板设计了覆盖矩阵的概念。在写测试代码之前先要求 AI 输出一张表测试覆盖矩阵用 markdown 表格输出 | 场景 | 输入 | 预期结果 | 边界/异常点 |比如测一个订单金额计算函数矩阵里会列出正常金额、两位小数精确进位、零元订单、负数金额、超大数值溢出、空数组。AI 先把矩阵列出来再根据矩阵逐个写测试用例。这个过程不是为了走形式而是逼着它思考“哪些输入会导致分支变化”把遗漏的盲区提前暴露。实际使用中我经常会在矩阵阶段就喊停修正。比如 AI 忘了考虑除零异常我在它写代码前补上这一行它后续生成的测试就会自动覆盖。相反如果一开始就让它直接写测试少了一个场景往往要等测试跑挂了或者自己 review 时才发现。先列矩阵再写代码省的是后端的纠错成本。4. 从零搭建模板库的实操记录4.1 目录初始化与第一版模板搭建模板库不用追求一步到位。我建议第一天只建目录和一个模板。我自己的第一版就是从 code-review 模板开始的因为它的回报最直接。先用一条命令初始化mkdir -p templates然后把验证过的审查模板放进去命名 code-review.md。所谓验证过是指这个模板的内容至少在真实的代码审查场景里跑过三次以上不是拍脑袋写的。没跑过的内容先放草稿区避免污染主模板库。我通常会在 templates 目录外再建一个 drafts 目录草稿模板反复打磨到足够成熟再正式收入模板库。这里有一个实操心得每份模板的正文里我会在最底部单独放两节叫“实测记录”和“上次改动”。实测记录写下最近三次使用场景和结果比如“2025-XX-XX 用于支付网关重构审查捞出一个回调验签问题”。下次打开模板时这些记录能提醒我模板是在什么背景下设计出来的改起来更有分寸。4.2 让 Claude Code 主动使用模板CLAUDE.md 配置模板建好之后关键问题是让 Claude Code 知道什么场景该用哪份模板。最直接的方式是每次对话手动复制模板内容但这样靠记忆触发久了容易忘。更稳妥的做法是在项目根目录的 CLAUDE.md 里注册模板的调用规则# 项目协作规范 - 当我要提交代码审查时请先阅读 templates/code-review.md并严格按照其中的流程执行 - 当要求开发新功能时请先阅读 templates/feature-dev.md - 当要求重构现有代码时请先阅读 templates/refactor.md - 当要求补充测试用例时请先阅读 templates/test-gen.md - 其他日常对话无需加载模板保持轻量。注意我写了最后一条豁免规则。这是刻意加的因为模板不能覆盖所有对话日常问答、思路讨论如果也要先读模板上下文会被无谓占用。让模板按场景触发、按需加载比“全局强制”有效得多。如果所有对话都强制加载整套模板Claude Code 的上下文会被占去相当一部分反而影响核心任务的质量。注册好之后测试一次。比如发一句“帮我 review 一下本次改动”然后观察它是否主动去读取模板文件并且输出格式符合预期。如果它没有读模板下一步排查我先看 CLAUDE.md 的指令是否排在对话早期以及表述是不是足够指令化。如果仍然无效就手动把模板路径写进对话里比如“请先读取 templates/code-review.md再按其中要求执行”。4.3 模板的迭代节奏模板库里没有“一劳永逸”这个说法。我自己的迭代节奏是每遇到一次翻车现场就记一张卡片内容包含“期望什么、实际发生了什么、哪里没约束住”。攒到三张同类卡片就去更新对应模板。比如最早重构模板里只有“不改变对外接口”一条铁律后来连续两次翻车都是格式被乱改我才把“不修改与重构无关的代码格式”补进去。这类改动说明模板设计是一个持续收敛的过程它不是从某个权威源头抄来的而是从你自己的失败记录里长出来的。给每个模板加一个简单的 changelog 也很有用。不用写详细只要写版本号和改动原因。这样当输出质量突然变化时可以快速倒查是哪次模板调整引起的。我遇到过一种情况某个模板突然不好使了翻 changelog 才发现前一天给“步骤”加了一条新规则和后面“输出”段的格式要求产生了冲突。有了版本记录这类问题几分钟就能定位。5. 真实使用中的常见问题与排查5.1 模板被忽略AI 当没看见最常遇到的问题就是模板明明写在 CLAUDE.md 里对话时 AI 却完全没按模板流程走。第一次碰到时我以为是工具坏了排查后发现多半是触发指令不够醒目。CLAUDE.md 内容长的话模型在构造回答时可能没有把后半段规则纳入高优先级。解决方式有两种一是把模板触发指令写到 CLAUDE.md 的最前面靠近角色定义的位置二是把指令说得更具体比如“在执行代码审查前必须先读取 templates/code-review.md再开始任何分析动作”而不是笼统说“参考审查模板”。如果还不行就在当次对话里直接粘贴模板的核心段落优先保证这次运行合规再去调系统配置。5.2 模板流程被 AI 跳过有时模板里明确写了“先输出方案等我确认再写代码”但 AI 还是把方案和代码一起输出。这不是指令冲突更像任务惰性——模型默认用户期望完整结果所以会尽量把任务“做完”。我的对策是两条腿走路先把模板里的步骤动词改成强制句式例如“禁止直接编写代码”“必须等待用户确认”如果仍然无效就调整输出格式要求方案以代码块的形式单独输出并在方案末尾写“已停止等待确认”。这种强阻断的输出格式比自然语言约束更可靠因为模型对格式信号的感知通常比语义更敏感。我说不清背后的原理但实测下来让它“输出一个代码块结束”比让它“先不要写代码”管用得多。5.3 模板太长上下文被占太多模板越长加载后占用的上下文就越多。上下文是 AI 编程最宝贵的资源所以模板设计必须做减法。我的经验是一行能说明白的约束绝不用三行能用规则列表表达的别展开成大段定义。如果一份模板确实长那就拆成主文件和子模块。比如“重构模板”可以拆成主流程模板加测试兜底规则两个文件。任务是重构时只加载主流程需要补测试再按需读取子模块。这种拆法的效果立竿见影长对话后期的“健忘”现象明显减少。我最初把测试生成规则完整写进了重构模板结果重构任务一加载就吃掉不少上下文拆分之后对话明显更轻快。5.4 常见问题排查速查表现象常见原因处理建议模板根本没加载CLAUDE.md 指令靠后/表述模糊把触发规则前置动词改具体流程被跳过输出未做格式阻断方案改为单独代码块要求显式等待确认上下文紧张模板单体过长拆分模板按需加载子模块输出格式不符模板里格式描述不够具体提供明确的 JSON 或表格样例模板过于死板所有步骤都是“必须”给部分步骤加“如果...则可以跳过”的弹性分支模板回归变差某次改动引入冲突查看模板 changelog回滚到上一个稳定版本6. 把模板库变成长期资产6.1 个人层面的长期收益用模板几个月下来我最大的感觉是自己的“提示能力”被沉淀成了可重复使用的东西。以前调教 AI 靠即兴发挥这次效果好下次换个项目又忘光了。现在每次调教成功的片段都会被提炼进对应模板效果等于在不断给模板库“加索引”。这也带来了一个很实际的好处换新项目时模板库可以直接迁移。新建一个仓库拷贝 templates 目录和 CLAUDE.md 的两段配置立刻拥有之前积累的全部协作规范。不需要重新和 AI 磨合第一天的对话质量就接近老项目的水平。6.2 团队复用的注意事项如果要把模板库推到团队层面考虑的东西会多一层。模板文件本身要进 Git 仓库团队里任何人的修改都要经过 review否则模板会像代码一样腐化。一份审查模板如果被不同人各自加了几条偏好规则到后面对 AI 的约束会越来越紧输出可能变得离题。还要给每份模板指定 owner。比如后端接口相关模板由后端负责人维护测试相关模板由质量负责人维护。owner 的意思是当团队其他成员对模板提出异议时由该人决定是否改动。没有 owner 的模板库最后通常会被改成一锅粥。最后记得定期清理“僵尸模板”连续一个月没被使用的模板先移入 archive 目录不要在正式目录里堆积。6.3 最后分享一点体会有一回我在一个刚搭好的模板库上跑通了一个旧功能的重构中间几乎没有人工干预从方案到测试全部按预设计划走完。那个瞬间我意识到模板的价值不是让我们少打字而是把“和 AI 高效协作的方法论”真正固化了下来。如果说代码库是我们的第一份资产这套模板库完全可以当成第二份资产来经营。它记录了你怎么思考、怎么下达指令、怎么验收结果是你和 AI 之间逐渐磨合出来的标准接口。以后每踩一个新坑我都会先想一个问题这个坑能不能变成一条模板规则能就顺手补进库里。模板库不是所有答案的起点而是每一次踩坑之后沉淀下来的终点。