最近在折腾Claude Code的模板化玩法顺手把散落在各个项目里的提示词、工作流、配置片段收拢成了一个仓库名字就叫claude-code-templates。简单说这仓库里装的是能让Claude Code按固定套路干活的预置指令代码审查、生成单元测试、写Git提交信息、整理Changelog、分析日志、修Bug全都可以抽成模板。有人会问跟Claude Code直接对话不就行了为什么非要模板因为日常开发里大量任务是重复的每次重新描述需求既费Token又容易漏条件而模板把这种重复劳动封装成了可复用资产。这篇文章我就从模板的设计思路、目录结构、完整示例到踩坑经验全部摊开讲一遍适合那些想用Claude Code提高效率但还没找到标准化套路的开发者。1. Claude Code模板的核心价值与设计思路1.1 模板到底解决什么问题先说一个我自己的场景。以前我用Claude Code做代码审查每次都得重新描述一遍要求审查安全性、性能、可读性输出问题列表给出严重级别。第一次这么做觉得没什么第十次就发现不对劲了——我花在描述规则上的时间比实际审查代码的时间还多而且一旦某天忘了说“输出严重级别”结果就是一堆没有优先级的长文本根本没法用。模板的价值恰恰在于把这种“稳定需求”固化下来。凡是重复超过三次的任务都值得抽成模板。具体能解决这么几类问题让输入标准化。同样一个代码片段不同人发过来格式不一样模板里用统一的上下文标记Claude Code能更快定位代码区域。让输出有下限。模板里写死“每个问题必须包含文件路径和行号”就算模型某个维度没看全输出结构至少是完整的不会出现一篇散文式回复。降低使用门槛。新人不用知道怎么跟Claude Code“说人话”直接运行模板脚本填入参数就能得到可用结果。沉淀团队经验。哪个项目容易出安全问题、哪种日志格式最有效都能通过模板不断沉淀。所以我的判断是模板不是一个“加分项”而是把Claude Code从玩具变成工程化工具的关键一步。没有模板的时候Claude Code是个聪明但随机的实习生有了模板它才变成一个守纪律、可预测的团队成员。1.2 模板的几种常见形态在整理仓库的过程中我发现很多人把模板简单理解成“一段提示词”其实并不准确。根据使用场景和复杂度的不同我习惯把模板分成四类。提示词模板是最常见的一种本质是一段结构化的提示词文本配合占位符使用。适合单次、独立的生成任务比如“给这个函数写一下JSDoc注释”“把这个错误信息翻译成用户友好的描述”。这种模板写起来快改起来也快是我仓库里数量最多的一类。技能模板则更进一步它不只是提示词还会绑定工具调用或执行步骤。比如日志分析模板不仅要告诉Claude Code怎么分析还要指导它调用CLI工具读取日志文件、过滤关键词、统计异常次数。这种模板的产出更像是一套“行为规范”而不是单纯的文本指令。配置模板用于初始化项目环境。Claude Code会读取项目中的.claude目录配置包括系统提示词、命令白名单、文件忽略规则等。配置模板就是把这些内容按统一格式生成出来避免每个新项目都从零写一遍。工作流模板负责把多个步骤串联起来解决“先做什么、再做什么”的问题。比如发布检查清单先拉取Git diff再检查是否缺少测试、是否有硬编码、是否更新了文档最后生成发布摘要。工作流模板更像是给Claude Code编排了一张待办清单。类型核心作用典型场景复杂度提示词模板固定提示词变量代码审查、注释生成低技能模板提示词工具调用日志分析、API调试中配置模板初始化项目配置新项目环境搭建低工作流模板多步骤串联发布检查、Bug修复流程高这四类模板不是孤立的实际使用中经常组合。比如工作流模板里会引用多个提示词模板技能模板里也会用到配置模板里的命令白名单。初期不需要把分类做得太细但脑子里有这个框架写模板时思路会清晰很多。1.3 设计模板前先定义“输入-处理-输出”我踩过最大的坑就是没想清楚模板要什么就把提示词一堆乱写。后来发现一个有效的模板其实很像一个函数它得有明确的参数列表得知道传入什么代码、什么上下文得有清晰的处理逻辑也就是告诉模型怎么分析、怎么思考还得有可预期的输出契约规定返回什么结构。所以我在每个模板文件的最上方都会加一段“元信息头”用注释的方式写明三个部分# 模板用途对指定代码片段执行安全、性能、可读性审查 # 输入参数代码片段、项目语言、关键业务约束 # 输出格式问题列表按严重程度排序附带文件路径和行号这段头注释不是写给模型看的是写给使用模板的人看的。它能帮你在几秒钟内判断这个模板适不适用也方便你后期快速检索。更关键的是它逼着我们在设计模板时先思考“输入是什么、输出是什么”而不是一上来就堆提示词。如果连输入输出都定义不清楚那这个模板就不该被创建。举个反例有段时间我想做一个“优化代码”的模板但“优化”这个输入太模糊了——优化性能优化可读性优化依赖没有明确的输入约束模型就会凭感觉发挥十次有八次输出不是我想要的。后来我把模板拆成了“性能优化”和“可读性优化”两个独立模板每个模板都写明输入和输出问题立刻解决了。2. 高质量模板的核心要素拆解2.1 角色与目标的设定角色设定对模型输出的影响非常大这一点在Claude Code上体现得尤其明显。同一段代码你让“资深安全工程师”和让“普通开发”分别审查后者往往会给出一些正确的废话比如“建议增加日志”或者“考虑使用更高效的方法”但前者会直接指出具体的漏洞类型、攻击路径和修复建议。所以我在模板里几乎都会设定角色。角色不一定要多复杂但要足够具体并且尽量贴合任务领域。比如代码审查模板里我写的是“你是一位资深代码审查专家擅长安全、性能、可读性三方面”日志分析模板里则是“你是一位SRE工程师熟悉分布式系统故障排查”。目标设定同样关键。角色决定思考角度目标决定输出导向。一个模糊的目标比如“分析这段代码”模型大概率会输出一段泛泛而谈的总结而“找出3个最可能导致内存泄漏的点并按风险从高到低排列”就会逼着模型聚焦在具体问题上。写目标时我习惯用数字和可验证的词语例如“列出”“找出”“给出”都比“分析”“评估”更容易得到结构化结果。2.2 上下文的注入方式上下文是模板的生命线。没有上下文Claude Code再聪明也只能靠猜。但上下文不能一股脑全塞进模板里否则模板会变得又长又乱。我的做法是把上下文分成静态和动态两类。静态上下文是固定不变的内容项目背景、使用的技术栈、团队编码规范、产品逻辑等。这部分适合直接写死在模板里因为它每个项目都相同写死能减少每次输入的成本。动态上下文则是每次使用时要替换的内容当前代码片段、Git diff、报错日志、特定文件路径等。这部分需要被显式标记出来方便模型识别。动态上下文我习惯用context标签包裹并在前面加一行说明。比如以下是待审查的代码片段请仅针对该片段输出结果不要推断片段外的逻辑 context {{CODE_SNIPPET}} /context这样做的目的是给模型划定一个明确的注意力范围。Claude Code在处理长文本时如果动态内容没有被标记可能会把示例代码当作参考语料而不是待处理对象。有了标签后模型的聚焦能力会明显提升。实测下来同样的代码审查模板加上context标签后误报率大概降低了三成。2.3 约束条件与输出格式约束条件决定了模板的下限。一个没有约束的模板结果可能是“看起来合理但实际没用”。我在模板里通常会加三类约束第一类是边界约束告诉模型哪些事情不能做。比如“不要修改业务逻辑”“不要调用不存在的API”“不要输出与本次审查无关的内容”。这类约束能防止模型自由发挥把简单任务变成发散式写作。第二类是质量标准告诉模型什么情况下算是合格。比如“每个问题必须指出文件路径和行号”“建议必须有可执行的修复代码”“如果未发现问题直接回复‘未发现明显问题’”。这类约束越具体越好最好能机械性判断。第三类是输出格式约束这是最容易被忽略但最重要的部分。Claude Code的输出是基于自然语言的如果不做格式约束哪怕内容正确也难以上自动化流程。我一般会要求用Markdown列表、表格或JSON结构输出。比如代码审查模板的输出格式是## 问题列表 - **严重程度**高/中/低 - **文件位置**src/index.js:12 - **问题描述**... - **修复建议**...格式约束的意义不只是好看它让后续处理变得简单。我可以直接把这个输出喂给脚本生成Issue列表或者粘贴到Review工具里。模板的“工程化”价值很大程度就体现在这里。2.4 变量与动态参数的替换机制关于变量Claude Code本身并没有像Jinja2那样的通用模板引擎但我们可以用脚本配合实现动态替换。我试过几种方式各有优劣。第一种是shell变量替换。在模板中用{{PLACEHOLDER}}标记然后在调用前用sed或${VAR}替换。优点是简单直接缺点是当替换内容里含有$、反引号、反斜杠等特殊字符时很容易出错。我在一次模板调用中代码里恰好有反引号结果整个模板被shell解析得乱七八糟输出完全不可用。第二种是使用临时文件。把动态内容写入临时文件再用$(cat tempfile)读取并注入模板。这样至少能避免单行替换时的逃逸问题。但如果动态内容本身包含大量特殊字符仍需小心处理。第三种是尽量借助Claude Code自身的文件上下文能力。直接把动态内容放在一个临时文件中然后在模板中写明“请读取/tmp/context.txt文件对其进行审查”。Claude Code可以读取本地文件这样就不需要做模板字符串替换规避了所有shell转义问题。代价是你要先准备好上下文文件流程上多一步。我的经验是模板内部统一使用变量名作为占位符对外提供脚本时再根据实际情况选择替换方案。占位符的标记越显眼越好避免与普通文本混淆。3. 从零搭建一个claude-code-templates仓库3.1 目录结构与命名规范一个模板仓库能不能被长期使用目录结构是关键。刚开始我也试过把所有文件堆在一个目录里结果一个月后自己都找不到“那个日志分析模板”放哪了。后来我重新整理按类型分了四个目录claude-code-templates/ ├── README.md ├── prompts/ │ ├── code-review.md │ ├── unit-test.md │ ├── git-commit.md │ └── bug-fix.md ├── skills/ │ ├── log-analysis.md │ └── api-debug.md ├── configs/ │ └── claude-config.example.md └── workflows/ └── release-checklist.mdprompts/放提示词模板每一个都是独立的Markdown文件可以直接复制使用。skills/放技能模板里面除了提示词还会描述工具调用步骤和对应的CLI命令。configs/放配置模板通常是.claude目录下的配置样例比如claude-config.example.md。workflows/放工作流模板一个文件描述完整的多步骤流程引用prompts和skills目录中的模板。命名规范上我坚持用全小写、短横线分隔的方式文件名必须能直接看出用途。code-review.md比cr.md好unit-test.md比test.md好。文件名真的是最小的文档别在这上面偷懒。README里我会写清楚每个模板的适用场景、输入参数、输出格式和依赖条件。这样即使是完全没接触过仓库的人也能按图索骥。我也建议每个模板文件头部保留我前面说的“元信息头”这是团队协作时最容易忽略却最实用的设计。3.2 一个代码审查模板的完整示例下面这个代码审查模板是我在仓库里用得最频繁的一个完整内容如下# 模板用途对指定代码片段执行安全、性能、可读性审查 # 输入参数代码片段、项目语言、关键业务约束 # 输出格式问题列表按严重程度排序 你是一位资深代码审查专家擅长安全、性能和可读性三个维度的代码审查。 请按以下步骤执行 1. 阅读上下文中的代码片段确认你理解了它的功能。 2. 依次从安全、性能、可读性、兼容性四个维度分析。 3. 对每个发现的问题按严重程度给出评级高/中/低。 约束条件 - 不要为了建议而建议只报告真实存在且值得修改的问题。 - 每个问题必须指出文件路径和行号。 - 如果没有发现问题直接回复“未发现明显问题”。 输出格式 ## 问题列表 - **严重程度**高 - **文件位置**src/index.js:12 - **问题描述**... - **修复建议**... 代码片段 context {{CODE_SNIPPET}} /context这个模板最开始只有安全、性能两个维度后来在一次前端项目审查中模型漏掉了一个兼容性问题导致后续在旧浏览器上出了bug。于是我在模板里加上了“兼容性”维度并在约束条件里加了“不要为了建议而建议”——因为我有过一段提示词写得太“鼓励输出”结果模型对每行代码都提出修改建议噪音极高。使用这个模板时我会先把代码片段替换进{{CODE_SNIPPET}}然后整体发给Claude Code。输出通常是结构清晰的列表我直接复制到代码评审平台上就能用。修改过一次模板后我还专门把“输出格式”部分加上了示例模型对格式的遵守率提升非常明显。3.3 一个单元测试生成模板单元测试生成是另一个高频场景。我的模板如下# 模板用途根据类或函数生成单元测试 # 输入参数源码、测试框架、测试命名约定 # 输出格式可运行的测试文件含必要注释 你是一位测试工程师擅长为业务代码编写高质量的单元测试。 请针对下面的源码编写单元测试。 要求 - 使用{{TEST_FRAMEWORK}}测试框架。 - 覆盖正常路径、边界条件、异常路径。 - 每个测试用例必须包含清晰的输入和预期输出。 - 断言必须具体不能使用恒真的断言例如 expect(true).toBe(true)。 - 如果源码存在外部依赖请使用Mock隔离。 - 测试命名遵循{{TEST_NAMING_CONVENTION}}。 源码 context {{SOURCE_CODE}} /context使用这个模板时我会传入两个参数测试框架比如Jest、pytest和命名约定比如should_xxx或test_xxx。模板的价值在于它强制模型考虑了边界条件和异常路径而这两条是手动写提示词时最容易忘的。我印象最深的是一次对一个日期处理函数生成测试模型不仅生成了正常日期、闰年二月的测试还主动写了时区偏移的边界用例。这个边界用例是之前我们人工测试时漏掉的。更妙的是模型在测试文件头部写了一句“依赖存在时区相关Mock请先配置环境变量”这种主动提醒极大减少了测试跑挂后的排查时间。当然生成的测试代码不能直接无脑提交。我会让Claude Code把测试文件输出到临时文件然后用人工过一遍。模板里特意没有要求“测试必须全部通过”因为模型无法执行测试但它可以基于静态分析推测哪些地方容易有问题。这一步靠的是模型的经验而不是模板的魔法。3.4 如何让模板在Claude Code中快速调用如果每次都要手动打开文件复制模板效率还是低。我给自己写了一套简单的shell脚本把模板调用封装成命令。以代码审查模板为例脚本逻辑如下#!/bin/bash # review.sh - 使用代码审查模板审查指定文件 TEMPLATE$(cat prompts/code-review.md) CODE$(cat $1) TEMPLATE${TEMPLATE//{{CODE_SNIPPET}}/$CODE} echo $TEMPLATE | claude -p这个脚本会把指定文件的内容替换到模板占位符中再通过Claude Code的-p参数print模式把整个模板作为提示词传入。使用方式是./review.sh src/index.js实际运行中要注意几点。第一这个简化脚本没有处理特殊字符转义如果代码里含有$、反引号、反斜杠替换会出错。更稳妥的方案是使用临时文件加$(cat tempfile)或者干脆换成“读取文件路径”的模板写法让Claude Code自己读取文件。第二Claude Code CLI的参数名在不同版本里可能有变化比如旧版本用--append新版本可能已经改成了别的名字最好先跑一遍claude --help确认。第三如果有多个文件需要审查可以循环调用脚本但要注意控制上下文长度建议一次只审查一个文件或一个小改动。4. 实操中的常见问题与排查实录4.1 模板明明写了却不生效“模板不生效”是我在群里被问到最多的问题。出现这个现象九成是因为模板本身在传递过程中被破坏了。我第一次遇到时模板里的代码片段在替换后格式错乱所有Markdown标题都挤到了同一行Claude Code完全没法识别指令。排查方法很直接先打印替换后的模板内容肉眼检查一遍。如果是shell替换导致的问题就不要在脚本里用复杂替换改成临时文件写入动态内容。如果是模板文件编码问题比如Windows的换行符CRLF用dos2unix转一下编码。还有一个容易被忽视的点模板文件别用UTF-8 BOM开头否则第一行指令会被BOM字符干扰。如果模板内容确认没被破坏但Claude Code还是“不听话”那就得检查模板里是否有自相矛盾的指令。比如一边说“只报告高严重程度问题”另一边又说“列出所有发现的潜在风险”模型会在两者之间摇摆。遇到这种情况把冲突指令删掉只保留最核心的一条。4.2 变量替换后上下文太乱这种情况大多出现在动态内容含特殊字符的时候。我踩过最惨的一次是要审查一段包含正则表达式的代码里面全是$、\、[、]shell变量替换直接炸了模板变成了乱码。后来我改用两条策略。第一条策略把动态内容写入临时文件然后通过$(cat tempfile)读取。这种方法能避免大量转义问题但仍然要小心引号。第二条策略改用“让Claude Code读取文件”的模式。模板里不再写{{CODE_SNIPPET}}而是写“请打开文件/tmp/target_code.js读取其内容并进行审查”。然后我先把代码写入临时文件再调用Claude Code。这个方案几乎完全绕开了shell转义唯一代价是要额外准备一次临时文件。我更推荐第二条策略因为它更符合Claude Code的能力模型。让模型自己读取文件比把一大段文本塞进提示词更可靠。尤其是在处理大文件时模型还能边读边梳理结构。4.3 输出格式与预期不符模板中已经明确写了输出格式但Claude Code有时还是会给出额外解释或遗漏字段。我的经验是光说“请按格式输出”不够最好在模板里给一个“输出示例”。我在Git提交信息模板里最初只写了“输出格式type(scope): subject”结果模型的输出经常是“feat: 添加用户登录功能”这种不完整的格式或者多了一行解释性文字。后来我在模板末尾加了一个示例输出示例 feat(auth): add user login flow加了示例后输出符合率从60%提升到了90%以上。原因是模型在生成文本时会自觉模仿最近出现的格式。所以如果你有明确的格式要求不要只描述格式直接把示例放进去。4.4 模板太长导致上下文超限Claude Code对单次输入Token有上限。模板里冗长的静态描述、示例代码和历史指令会占掉大量空间留给动态内容的就少了。当代码文件稍大时经常出现“模板内容被截断”的情况。我的解决方案是把模板拆成两层。公共层是每个项目都适用的核心约束和角色设定写在.claude/claude_config.md里作为系统提示词常驻。私有层是每次任务特有的指令通过CLI的--append参数传给Claude Code。这样既保证了核心约束不丢又能给动态内容留出足够的Token空间。另外模板内容也要精简。一些废话式指令比如“请认真阅读”“请仔细分析”完全没必要写进模板它们只会占用Token且不产生实际效果。写模板的最高境界是“每句话都有用”。5. 模板的管理、版本化与团队协作5.1 用Git管理模板版本模板和代码一样需要版本管理。我的claude-code-templates仓库本身就是Git仓库每次修改模板都会提交一次提交信息里会写明改了什么、为什么改。例如“code-review模板增加兼容性维度修复旧浏览器漏洞遗漏”。版本管理最大的好处是可以回滚。有一次我把一个模板改成了全英文结果团队里同事用不惯效果反而变差。靠着Git revert我30秒就把模板恢复到之前的中文版本。没有版本管理这种回滚就只能靠记忆非常不靠谱。我还会在Git里维护一个“模板效果记录”的文档记录每次使用模板生成结果的人工评分和改进建议。这个文档不用很正式一个表格就行模板名称使用时间结果评级问题与改进code-review2025-01-128/10漏了一个并发安全点模板增加并发维度unit-test2025-01-137/10覆盖不足补充边界条件要求这份记录是模板迭代最重要的依据。5.2 团队共享模板的注意事项团队协作时模板最大的争议是“风格”。有人希望模板输出中文有人习惯看英文有人要详细解释有人只要结论。我在团队里推行模板时踩了不少坑最后的经验是模板只规定流程和必备字段不限制语气和详略。也就是模板里写死“必须包含文件路径和行号”但不写死“必须用中文”或“必须用英文”。语气偏好交给使用者通过变量传入。这样团队既能保持统一又不会因为个人习惯不同而互相抵触。另外团队共享模板一定要配README。README里写明每个模板的适用场景、参数说明、调用方法最好再给一个最小可用示例。没有README的模板仓库用起来就是灾难——同事根本不知道unit-test.md里{{TEST_FRAMEWORK}}应该填什么。还要注意认证和权限。如果模板里有敏感API地址或者内部服务路径建议用占位符替代不要在模板里硬编码。团队贡献模板时代码审查应该覆盖到模板内容本身而不只是业务代码。5.3 模板的迭代与反馈闭环模板不是一次性产物它需要持续迭代。我使用的闭环很简单每次用模板生成结果后先人工审核这次结果的质量如果发现模板导致的问题立刻记录并修改模板。修改完模板后还要再用同一个用例跑一遍验证是否真正解决。举个例子我的代码审查模板第一次迭代前只要求“从安全、性能两个维度审查”结果在一次并发项目审查中漏掉了线程安全问题。我就在模板里加了“并发安全”维度并备注“必须检查共享变量和锁的使用”。第二次迭代时发现输出太啰嗦我又加了“不要为了建议而建议”这条约束。第三次迭代我增加了“每个问题必须指出文件路径和行号”因为人工核对问题时发现定位成本太高。每一次迭代都来自真实使用的反馈而不是凭空想象。这个闭环看起来笨拙但效果极好。一年多下来我的模板从最初的两个增加到了二十多个但删除的模板数量也差不多一样多。删除不代表失败反而说明你越来越清楚什么是有用的。最后分享一个小经验不要试图一次设计出“万能模板”一个模板只解决一个问题反而更好维护。我自己的这个claude-code-templates仓库就是从两三个模板开始的现在已经有二十多个但这过程里删掉的模板和新增的一样多。如果你也在整理自己的模板库记住模板不是越复杂越好而是越稳定越好。真正的好模板是在一次次真实使用中打磨出来的不是在桌面上憋出来的。
