1. 用模板之前先想清楚要解决什么问题我在项目里挂上claude-code-templates这个名字的时候其实不是想做一个炫酷的提示词集合而是被一个很实在的问题逼的每次打开一个新的 Claude Code 会话我都得像第一次见面那样把项目背景、代码位置、技术约束、期望输出重新交代一遍。对话稍微长一点风格就开始飘之前定好的规范它慢慢就不遵守了。这个模板库做的东西很简单把那些重复写了无数遍的上下文、约束、验收标准沉淀成一套可以反复调用的文件结构。它解决的就是两件事——减少每次会话前那段重新自我介绍的废话以及让模型输出保持在一个稳定的质量区间里而不是每次全凭运气。适合看这篇文章的人我默认你已经在用 Claude Code 写代码了至少被它生成过几百行代码并且对它的发挥不稳定有点体会。如果你刚开始接触也没关系文里的思路大部分是通用的换成其他编程助手一样成立。2. 模板库的整体架构与目录规划2.1 按任务类型分目录而不是按语言分这是我自己踩过的一个大坑。一开始我建模板库第一反应是按技术栈分python/、javascript/、go/各一个目录每个目录下面放代码片段。结果用了两周发现实际开发里我根本不会因为今天写 Python就去翻 Python 目录而是因为今天要做代码审查、要补测试、要拆需求才会去翻模板。按语言分是静态思维按任务类型分才是动态思维。语言只是模板里的变量任务流程才是真正决定模型表现的东西。比如代码审查不管你是审查 Python 还是 JavaScript流程都是一样的先读代码、找问题、按严重级别归类、给修改建议。骨架完全相同只是具体判断标准略有差异。我的目录结构长这样claude-code-templates/ ├── templates/ │ ├── planning/ # 需求拆解、任务规划 │ ├── review/ # 代码审查、设计评审 │ ├── testing/ # 单元测试、集成测试、测试计划 │ ├── refactoring/ # 代码重构、性能优化 │ ├── docs/ # 接口文档、技术方案说明 │ └── debug/ # 故障排查、问题定位 ├── scripts/ # 快速引用模板的小工具 ├── CHANGELOG.md # 模板变更记录 └── README.md # 模板使用说明planning/里放的是拿到需求之后怎么拆review/里放的是代码写完怎么审testing/里放的是功能做完怎么验。这样我坐在电脑前遇到什么场景就去哪个目录拿对应的壳子填入本次的任务内容直接开工。2.2 每个模板文件的三个固定部分我后来把每个模板文件都做成了同样的结构这样使用成本最低不需要每次回忆这个模板里我应该填什么。每个模板固定由三个部分组成角色设定可选给模型一个视角。比如你是一名有五年分布式系统经验的资深工程师这个不是玄学它确实会影响输出的口吻和关注点。同样是分析一段代码默认视角可能只告诉你逻辑问题加了资深工程师视角之后会额外指出可维护性和扩展性问题。任务上下文必填这是唯一需要我每次手动填写的部分包括项目背景、涉及的文件路径、技术约束、以及这次任务的目标。模板的价值就在于把每次都要想怎么写的内容固定成填空我只需要填值就行。输出要求必填这是整个模板里最重要但最容易被忽略的部分。不能只写请帮我审查代码而要写清楚输出格式是问题列表每个问题包含严重程度、所在文件与行号、问题描述、修改建议。输出要求定义的是验收标准模型拿到之后才知道什么算做完。这三个部分用分隔线在模板文件里明确区分用的时候打开文件把任务上下文部分替换掉其余不动直接丢给 Claude Code。3. 核心模板拆解与实操心法3.1 需求拆解模板把模糊需求变成可执行任务大多数项目里最大的浪费不是代码写得慢而是需求理解错了。Claude Code 不会读心你给它的是一条含糊的需求它还你一堆漂亮但偏离方向的代码。开发中我处理新需求的第一步永远是走需求拆解模板先把任务边界划出来。任务背景 用不超过3句话说明这个需求要解决什么问题面向哪个用户场景 现有系统约束 现有代码架构、技术栈、不允许大改的部分没有就填无 期望交付物 具体到什么程度算完成是方案文档、代码改动、还是测试用例 非目标 明确写清楚本次不做的事情防止模型顺手过度设计 验收标准 用当...时系统会...的格式描述可验证的行为这个模板设计的核心是把完成的定义交给提示词作者而不是交给模型猜测。我在使用中发现人脑最容易犯的毛病是只描述目标不描述边界而模型恰恰会在边界模糊时自作主张。举个例子你说把用户查询接口优化一下它可能重写整个模块但你加上非目标不改动数据库表结构、不引入新依赖它只会聚焦在查询逻辑上。验收标准这一栏要求写行为描述而不是代码描述这个细节很关键。代码描述是嘴巴上的行为描述是可测试的。比如当用户名长度超过20个字符时系统返回参数错误提示这句话不管最后代码怎么实现验收逻辑都是确定的。模板库的价值不在于提示词本身多长而在于它逼着你把思考补全。3.2 代码审查模板别让模型自己检查自己代码审查模板是我用下来之后效果最明显的一个。因为大多数编程助手都有同一个毛病让它生成代码然后紧接着让它审查自己的代码它倾向于自我辩护找出问题的意愿会大打折扣。这个不是玄学是因为模型在生成代码之后已经形成了对这段代码的所有权认知再让它挑自己的刺它会有倾向性。所以我做审查模板的时候刻意做了两个设计。第一个设计让模型先独立复述自己读到的代码逻辑再进入问题查找阶段。这样它必须先真正理解代码而不是点到为止扫描一遍。第二个设计明确要求只输出问题列表不输出修改后的代码。一旦要求它给出修改方案模型的注意力会转移到如何重写代码上面问题分析反而会弱化。角色设定 你是一名资深代码审查员正在对一段不属于你的代码做审查。 第一步-复述逻辑 先用200字以内复述这段代码的实际行为重点说明数据流和控制流。 第二步-问题列表 按照以下分类逐项检查并输出问题清单 | 分类 | 检查要点 | |---|---| | 逻辑正确性 | 边界条件、异常分支、并发安全 | | 资源管理 | 连接释放、内存使用、超时处理 | | API 误用 | 依赖版本、方法签名、废弃弃用 | | 安全风险 | 输入校验、权限控制、敏感信息泄露 | | 可维护性 | 命名、职责划分、重复代码 | 输出要求 1. 每个问题必须包含严重程度 具体原因 位置 2. 禁止输出修改后的完整代码只允许单行级修改建议 3. 如果某分类下没有发现问题明确写未发现问题这里我用了一个比较反直觉的做法让模型复述代码逻辑。一开始我也嫌这一步啰嗦但实测下来跳过这一步直接进入问题列表模型经常给出很泛的建议比如建议增加错误处理这种说了等于没说的废话。复述逻辑之后它真的会更聚焦于代码实际执行路径上的问题。3.3 测试生成模板先定行为再写用例让编程助手生成单元测试最让人头疼的是它总是生成那种验证一下函数能跑通的快乐路径测试对边界条件和异常路径几乎不碰。导致大量测试代码只是行数多覆盖率好看但那个最容易出 bug 的分支恰好没测到。测试生成模板的核心思路是不让模型直接写测试而是先让它根据代码行为画出行为规格表格然后基于表格生成用例。行为是先于代码的模型填写行为列表的时候就必须思考这段代码在各种输入下应该返回什么结果而不是随手写一堆断言。任务描述 针对 {文件路径} 中的 {函数名称} 生成单元测试。 第一步-行为梳理 用以下表格逐条列出该函数应该满足的行为规格 | 场景类型 | 输入描述 | 预期行为 | |---|---|---| | 正常路径 | ... | ... | | 边界值 | ... | ... | | 异常输入 | ... | ... | | 并发/状态 | ... | ... | 第二步-测试用例生成 基于行为规格表格中的每一行生成对应的测试用例。 要求 1. 测试函数命名使用 test_场景类型_行为描述 2. 每个用例必须有明确的断言禁止只调用无断言 3. 使用项目现有的测试框架不要引入新依赖这个表格我几乎每个项目都会用。它有个额外的好处当模型梳理行为规格时如果发现某个函数的代码逻辑跟预期行为对不上它会直接在表格里暴露出来。也就是说这个模板不只是生成测试还能作为代码理解的辅助工具。3.4 技术方案模板把约束写进前置条件很多人写代码时遇到复杂功能直接就问这个功能应该怎么做然后把模型给的第一版方案直接照着实现。这属于把方案设计的主动权完全交给了模型。等你发现方案里有硬伤可以说整个方向都走偏了因为它根本不知道你的系统里有什么约束。技术方案模板的设计出发点是把约束条件放到了问题的前面。你先把目标和边界讲清楚再让模型提出方案而且要求它提出多个候选方案做对比而不是只给一个答案。单一方案没有比较梯度关键问题根本暴露不出来。目标 用一句话描述最终要实现什么不涉及具体做法 前置约束 1. 现有技术栈是 {技术栈} 不引入与现有体系冲突的新组件 2. 性能要求接口 P95 延迟 200ms 3. 运维要求不支持新增常驻后台进程 4. 团队能力只有2名成员会维护新模块 候选方案要求 请给出 2-3 个候选设计方案每个方案按以下格式输出 方案名称 核心思路 实现路径 优点与代价 推荐程度 最终选择 基于上述约束说明你的推荐方案是哪一个并解释为什么。用这个模板之后我能感觉到输出质量明显不一样。模型在看到不支持新增常驻后台进程这种约束后会自动忽略需要后台任务才能实现的设计给出的方案更接地气。技术方案设计本质上就是约束下的最优化约束写得不明确方案就会飘。4. 实战流程把模板接入日常开发4.1 用模板跑通一次完整任务模板库光有文件不行关键是把模板变成日常开发的固定操作流。我拿一个最近真实做过的任务举例给项目里的UserService.queryUserById补充单元测试。以前我可能会直接打开 Claude Code 说帮我给这个函数写几个测试然后看看它的输出不行再改。现在我的流程是第一步打开templates/testing/下的测试生成模板把文件路径和函数名填进去。第二步把模板内容连同函数源码一起丢给 Claude Code。第三步等它输出行为规格表格之后我先不急着让它生成代码而是逐行看表格里的每一行是否与实际业务逻辑吻合。第四步确认表格没问题再让模型按表格生成测试代码。第五步跑测试把失败的用例回贴给它。这个流程多了确认行为规格这一步但恰恰是这一步能拦住大部分无效产出。模型生成的测试之所以对不上需求根源在它对业务的理解是错的这个错会在行为规格表里提前暴露。你可以让它修改而不是等生成测试代码之后才发现方向偏了。跑通一次之后我就把这个模板固定在README.md的使用说明里下次照做就行。模板库能不能被真正用起来不取决于文件多不多而取决于使用路径够不够短。一个模板如果在 30 秒内调不出来它跟不存在没有区别。4.2 模板的自定义与版本管理很多模板库做出来之后就成了一次性工具用两次就自己改了。但改模板是一件影响面很大的事情一不小心就会把本来好用的模板改成面目全非的东西。我从实际项目里吃过大亏之后开始把模板当作项目代码来管理纳入版本控制并且建立变更记录。模板在CHANGELOG.md里记录了三类改动新增模板、调整模板结构、修改提示词措辞。特别是措辞修改看起来很小但对模型输出的影响可能很大。比如我在审查模板里把请检查代码问题改成对不属于你的代码做审查就明显提升了问题清单的客观性因为不属于你三个字改变了模型的责任视角。模板版本的管理也要注意一个原则修改模板之前先备份当前版本。我在实践中使用了最朴素的方式在templates/review/目录下保留一个archive/文件夹把修订前的模板按日期存进去。因为经常会遇到一种情况新版本用了两天觉得输出反而不如旧版想回退但已经找不到原始内容了。git add -A git commit -m review模板增加逻辑复述步骤输出质量提升但耗时增加 git log --oneline -- templates/review/ git diff HEAD~1 HEAD -- templates/review/code_review.md版本管理和变更记录还有一个额外价值当模型的行为随版本变化时你能通过回看模板的修改历史定位是哪个措辞导致了变化。没有记录的话模板库就是一个越用越烂但没人知道原因的黑盒。5. 常见问题与排查技巧实录5.1 模板太长导致上下文被截断我在早期做模板库的时候犯了越多越好的错误一个需求拆解模板能写 3000 字里面塞满了各种案例和原则。结果在实际对话中模板占掉了大量上下文空间真正重要的项目描述和代码内容反而可能被截断模型的输出质量不升反降。这个问题的根源在于上下文窗口是有限的。模板的目的不是把所有知识都塞进去而是把必要的结构固定下来。后来我把所有模板都做了一次减脂只保留结构框架和最核心的规则具体的说明放在另一份使用文档里不给模型看。做个对比就清楚了做法模板长度模型输出表现我的使用体验全量模板2500字左右遵守率高但上下文紧张经常需要为代码内容腾空间精简模板700字左右关键规则遵守率稍降但总体稳定空间充裕配合上下文更灵活按需拼接300字起关键规则通过输出要求重复后保持最顺手推荐我现在的做法是精简骨架 关键规则尾部重复。一个模板只保留不可替代的骨架信息比如第一步复述逻辑、第二步输出问题清单这样的流程结构。最重要的两三条规则在输出要求里再写一遍。因为模型对提示词末尾的注意力天然强于中间把关键约束放在输出要求里遵守率反而更高。精简模板之后我会再把拆下来的说明文字放到README.md或者docs/目录里供自己查阅。模型不需要看长篇大论我需要理解的设计思路才需要文字记录。5.2 模型生成结果偏离模板要求模板写了要按格式输出但模型经常输出到一半就开始自由发挥。这个问题我排查了很久最后发现不是模板写得不够好而是违反了模型少即是多的注意力规律。模板开头写了一大堆规则最后只简单说了一句按此格式输出模型跑着跑着就把开头的规则丢了。解决的办法是在输出要求的部分把规则浓缩成一条并且放在最后强调。以审查模板为例我在开头写了五类审查维度但如果不在输出要求里再归纳一次模型往往会漏掉安全风险这一类。所以我在输出要求的末尾固定加一句注意输出必须严格按照问题列表格式每个问题必须分类归类且分类只能从 {逻辑正确性、资源管理、API 误用、安全风险、可维护性} 中选择。加了这个分类白名单之后模型的输出基本不会再冒出模板体系之外的分类。这个方法背后是模型理解的一个小规律给出选项的约束比给出描述性的约束更有效。描述性约束需要模型自己理解并归纳选项约束直接限制了它的输出空间。5.3 模板之间的复用与组合模板库不只是一堆独立的文件它们之间可以形成组合关系。我使用中发现需求拆解模板的输出结果恰好可以作为技术方案模板的输入技术方案模板的输出又可以作为代码审查模板的上下文。做好了这个组合关系模板的价值会指数级上升。我依据此给每个模板的头部增加了一个前置输入字段说明了该模板依赖什么内容。比如规划模板的输出标注此输出可用于技术方案模板的任务描述这样我处理完整流程时就知道一个任务应该依次调用哪些模板。这跟流水线组装一样前面的输出接后面的输入。还有一个常见问题是组合调用时上下文过长。我建议使用文件的方式传递中间产物而不是把上一步的全部输出复制到下一步的提示词里。比如需求拆解的结论可以写到本地文件下一步的模板里直接用文件引用和摘要这样模型既能理解上下文又不会因为过长而丢失重点。6. 个人在项目中的实用体会模板库用了几个项目之后我最大的感受是它真正的价值不在于提示词本身多精妙而在于维护它的过程逼你养成了结构化思考的习惯。以前我提需求凭感觉现在被模板逼着先想清楚边界、验收标准、非目标这本身对做技术方案就是实打实的好处。模型最终只是把它看到的逻辑执行出来你给它的结构越清晰它给你的结果越对齐。最后分享一个实用的小技巧模板文件名最好以动词 对象来命名比如analyze-code-review.md、plan-feature.md不要用template-01.md这种序号命名。因为你在 Claude Code 会话里经常要凭记忆写文件名来引用模板一个准确的动词命名能让你瞬间想起这个模板是干什么用的数字序号则完全做不到这一点。这套模板库我会继续维护下去每次在实际项目中感到它回答得不尽如人意的时候我都会先去检查模板而不是怪模型。大多数情况下改一下模板的表达方式比反复重试对话要高效得多。