我是从一次打脸经历开始触碰 claude-code-templates 的。第一次在真实项目里大规模让 Claude Code 干活，我的提示词只有一句：“排查一下这个页面缓存为什么失效。”结果它一口气改了七个文件，其中两个和问题完全无关，还顺手把本地环境配置给改坏了。那不是模型蠢，是我压根没给它一份像样的任务书。后面我花了两个月把代码审查、Bug 复现、项目脚手架、批量重构这些重复劳动全部沉淀成可复用的模板，才终于把工具用出了稳定效果。
这篇文章就把这套 claude-code-templates 的设计思路、目录结构、五个关键构件、三个可直接复制的实例，还有我踩过的六个坑全部写出来。适合已经在用或者正准备用 Claude Code 的开发者，也适合那些抱怨“AI 写代码不靠谱”的同行——多半不是模型不行，是你没给它一套稳定的指挥框架。
1. 为什么我舍得花两个月去打磨一套模板
1.1 先分清楚“写提示词”和“建模板”的区别
一次性的提示词解决的是单点问题，比如“帮我修复这个函数”——你对话里把上下文贴清楚，回答完就结束了。而模板解决的是一类重复问题，它把角色、背景、约束、步骤、验收标准全部固化成同一份任务说明书。
举个例子。我在 review 代码时浪费过大量时间，因为每次都要重新跟模型解释“只看本次改动、别管风格、按严重程度给结论、不要修代码只提建议”。这些规矩很琐碎，但每次都影响结果质量。把它们写进 review 模板以后，我只需要一条命令：/review PR-1234。模型自动知道该读哪些文件、该往哪个方向输出、哪些事坚决不能做。
1.2 模板真正解决的是可控性和可审计性
很多人以为模板是给 AI 用的，其实模板首先是给人用的。没有模板时，模型的行为像飘忽不定的实习生——做得漂亮是惊喜，做得离谱才是常态。有模板时，它的行为被约束在一个确定性的流程框架里，每次输出结构一致，review 成本直线下降。
我在模板里最常写的一句话不是“请认真分析”，而是“不许动任何未明确指定的文件”。这种负面约束比一百句“请仔细”都有用。原因很简单：模型训练时见过太多“热心帮手”的样例，它天然倾向于做多余的事。模板必须替它画出红线。
1.3 一套模板带来的四个现实收益
第一是可复现。同一个问题换个人来执行，只要调用同一个模板，产出形态基本一致，不会出现“十个人问出十种风格答案”的情况。
第二是可审计。模板要求模型在最后固定输出“改动文件清单 + 修改理由 + 验证命令 + 残余风险”，这让所有 AI 操作都留下了可检查的痕迹。
第三是省 token。与其让它自由发挥中途跑偏，不如开头多花几十个 token 把规矩说清楚。跑偏一次消耗的上下文窗口和返工时间，远超模板本身那点成本。
第四是拉平团队水平。把资深工程师脑子里那套排查思路、审查逻辑写成模板，新同学也能用出七八成功力。这不是替代经验，而是把经验可变现成流程。
2. 模板体系的目录结构与三条底层设计原则
2.1 模板文件的存放方式与命名纪律
我的模板全部放在独立目录下，一个工作流对应一个 Markdown 文件。目录长这样：
~/.claude/templates/review/：代码审查、变更风险评估~/.claude/templates/debug/：线上问题排查、Bug 复现与修复~/.claude/templates/scaffold/：新模块、新服务、新脚本脚手架~/.claude/templates/refactor/：批量重构、重命名、依赖升级~/.claude/templates/doc/：接口文档、架构说明、复盘报告
每个文件第一屏就用一两句话写清这个模板的适用场景和不适用场景。放在文件头部的描述字段是给人看的，因为我经常隔两周就忘掉某个模板当初是干嘛用的。文件名就是调用方式，所以命名必须动词开头、语义边界清晰，比如review-strict.md、debug-reproduce-first.md、scaffold-service.md，而不是help.md、test.md这种含糊名字。
2.2 底层原则一：先写“什么是成功”，再写“该怎么做”
模板第一段必须给出可验证的验收标准。AI 会不自觉地朝你描述的目标优化，如果你只说“帮我优化这段代码”，它就会按自己对“优化”的理解自由发挥。但如果你写“优化后必须保持接口兼容、全部单测通过、不改变日志格式、耗时降低 5% 以上”，它的行为立刻收敛。
这条原则在排障类模板里尤其重要。我踩过的典型场景是：让 AI 查一个偶发超时，它查着查着开始修改数据库连接池参数，理由是“这样也许能降低延迟”。可我们根本还没定位到根因。验收标准写清楚后，它再也不会越界去碰那些“也许有用”的地方了。
2.3 底层原则二：把“不要做”写满一整块
负面约束要单独成段，而且要写得比正面任务还细。正面任务给 AI 提供方向，负面约束给 AI 提供边界，两者缺一不可。
我常用的负面约束清单大致如下：
- 不要为了通过测试而删除或禁用测试用例。
- 不要修改任何与任务无关的已有函数签名。
- 不要新增第三方依赖，除非模板明确允许。
- 不要对未指定的目录做批量格式化。
- 不要给出“建议你手动处理”这种废话，要么动手，要么明确说无法自动完成。
这些条条框框看起来像是在“防贼”，但用过几次你就会发现，它们才是模板里价值密度最高的部分。
2.4 底层原则三：给步骤序列，不要给目标列表
同样是让 AI 排查 Bug，目标列表的写法是“找到根因并修复”；步骤序列的写法是“先复现，再列出所有变量，然后按二分法定位，最后给出最小修复”。后者多花了几行字，却让模型的行为从发散变成了收敛。
模板里凡是涉及修改代码的工作流，我都会强制插入五个步骤：复现现场、记录事实、列出假设、选择最少改动方案、验证并回滚确认。这套流程看起来笨拙，但恰恰是模型最需要的——它天生擅长跳跃式联想，反而不擅长老老实实按顺序推进。模板的作用就是逼它走完每一步。
3. 模板内嵌的五个关键构件
3.1 角色与项目上下文
角色设定不是为了“扮演”，而是为了让模型在有限上下文窗口中高效聚焦。我常在模板开头写明：“你是一个在此仓库工作的代码审查助手。项目背景见 README.md 开头 200 行。参考规范见 docs/CONVENTIONS.md。如果你发现规范与代码现实冲突，先记录冲突，不要擅自选择立场。”
这样写有两个好处。一是模型知道自己身处哪个代码库，说话用词、判断标准都会贴合项目实际；二是模型知道自己有“参考事项”和“冲突处理方式”，不会在遇到规范矛盾时自作聪明地乱猜。
3.2 变量入槽
模板必须支持参数插入，否则复用性会很差。我习惯把每次使用才会变化的点全部做成变量，比如分支名、PR 编号、新增服务的名称、目标日志文件的路径等。
模板里用${VAR}占位，调用时把参数传进去。一个典型调用是/debug-reproduce-first COUNTRY-23 用户端白屏最新包出现，模板内部自动把“问题编号”和“现象描述”填进对应的槽位。这样模板负责框架，调用者只负责提供本此任务的关键信息。
3.3 边界声明
边界声明是模板里最容易被新手忽略的部分。它回答的问题是：这次操作允许影响哪些范围？哪些目录是禁区？什么情况下必须停下来问人？
我常写的边界示例包括：
- 允许修改
src/services/下文件，禁止修改vendor/、node_modules/。 - 只有“出现编译失败”或“出现数据丢失风险”时，可以中断当前流程并请求人类决策。
- 涉及鉴权、支付、权限模型的文件一律只读，只能给出建议，不能直接改。
这些声明之所以重要，是因为模型没有“常识”。它看起来懂很多，但对“哪些文件动不得”这件事毫无概念，只能靠你明说。
3.4 强制证据化输出
模板必须要求模型在给出结论前列出观察到的客观事实。尤其在代码审查和 Bug 排查类模板里，我会显式写出：“每个结论必须附带文件路径、行号、日志片段或 diff 证据；没有证据的结论标记为怀疑项，不得作为修复依据。”
这样做可以显著降低模型“一本正经胡说八道”的概率。当它知道自己写的每个判断都要被要求附依据时，它会倾向于少给模糊判断，多给能验证的信息。
3.5 固定的输出格式与验收清单
模板最后，我会要求模型按照固定结构输出：改动文件清单、每个文件改了什么、为什么改、验证命令、残余风险、是否有需要人工确认的决策。这个固定出口非常重要，它让模型把“完成”定义成“写满这张表”，而不是“陪用户聊到开心”。
验收清单则是给人类看的检查表。模型在模板里自带一份 step-by-step 清单，结束前必须逐项打勾。我看结果时，只需要对照清单核对它的自检是否诚实，而不需要从头理解它做了什么。
4. 三个可以直接复制使用的模板实例
4.1 代码审查模板：从泛泛而谈变成分级评审
这是我最常用、也是收益最直接的模板。过去模型给的 review 意见经常是“建议增加注释”“建议提取公共方法”这类正确的废话。现在它会按严重程度和改动范围分层输出。
你是一个严格的代码审查助手，工作对象是本次 PR 涉及的改动文件。 背景：项目根目录有 README.md，规范在 docs/CONVENTIONS.md 中。只审查本次 diff， 不要审查与本次改动无关的历史代码。 任务：分析给定 PR 分支与目标分支之间的 diff，按以下结构输出： - P0：会造成线上故障或数据损坏的问题，必须修正。 - P1：明显逻辑错误或边界条件缺失，强烈建议修正。 - P2：可维护性问题或轻微风格问题，仅供参考。 每个结论必须附上：文件路径、具体行号、问题描述、建议修改方向。 边界： - 不要直接修改代码，只输出评审意见。 - 不要评论未在 diff 中出现的函数。 - 不要因为没有写注释而打 P1，除非该函数确实晦涩到无法理解。 - 如果发现 diff 里包含数据库结构变更，单独提出来并标记为“需人工确认”。 最后输出格式： 1. 评审摘要（3 句话以内）。 2. 按严重程度分组的列表。 3. 你认为是误报的子项列表，并说明为什么。用这个模板后，PR 评审从“聊天式听写”变成了结构化审查报告。模型不再执着于挑措辞毛病，而是真正去看逻辑漏洞和边界风险。
4.2 Debug 模板：强制先复现，再动手
修 Bug 是模板收益最大的场景，因为模型天然喜欢“猜一个原因然后直接改”。为了保证它按排查逻辑走，我写了这个模板。
你是一位严谨的根因分析工程师。我提供一个缺陷现象，你的任务是定位根因并给出最小修复。 缺陷描述：${issue_description} 相关文件：${related_files} 复现步骤：${reproduction_steps} 执行流程： 1. 先判断复现步骤是否完整。如果缺少关键信息，列出需要补充的内容，不进行任何修改。 2. 复现后，列出当前现象涉及的五个以内的最可能变量。 3. 为每个变量写一行可观测的验证方式（日志字段、请求返回、数据库查询）。 4. 基于验证结果，收敛到最可能的根因。 5. 给出最小修复方案：只改根因位置，禁止顺带修复无关问题。 6. 执行修改后，跑模板指定的回归命令，并在输出中贴出结果。 边界： - 如果修复方案涉及三处以上文件同时改动，先停下来向你描述整体方案，等你确认。 - 禁止删除用例来让测试通过。 - 禁止在未确认根因前修改配置类文件。 输出格式： - 复现结果 - 候选假设列表 - 验证过程摘要 - 根因结论 - 修复 diff 摘要 - 回归验证结果 - 残余风险说明我把这模板用在一次棘手的偶发超时问题上。它没有直接去改代码，而是先要求我提供完整复现步骤。在我补上“只在成都地域偶发”这个关键信息后，它把变量列表收敛到数据库连接池和上游依赖两个方向，最终定位到某次发布引入的重试时间配置问题。整个排查链路看起来就像一个正常且耐心的老工程师在工作。
4.3 脚手架模板：把团队规范变成一键生成
新建服务时最有意思的矛盾是：一边希望大家遵循团队目录规范，一边每个人生成的目录结构都不同。脚手架模板解决的正是这个。
你是一个服务脚手架生成器。请按团队约定生成一个新的后端服务。 服务名称：${service_name} 技术栈：${stack} 需要暴露的接口：${endpoints} 项目规范文件放在 docs/ARCHITECTURE.md，必须严格遵循其中的目录结构、命名规则、 错误处理方式和日志格式。 生成内容： 1. 可运行的最小服务骨架，包含健康检查接口。 2. 按 ${endpoints} 列出空的业务处理函数，并配置好路由注册。 3. 每个处理函数必须包含：参数校验、统一错误响应、结构化日志。 4. 必要的测试文件：至少覆盖健康检查和每个接口的下发失败路径。 5. Dockerfile 与本地开发用的 compose 片段。 边界： - 不要引入额外的框架或中间件，除非 ARCHITECTURE.md 已明确要求。 - 不要生成数据库迁移脚本，除非你说需要。 - 生成的每个文件头部注明“由模板生成，建议按项目风格二次修改”。脚手架模板最大的价值不是让 AI 生成一坨可以用但没人看得懂的代码，而是在生成的第一刻就符合团队约定。新人再也不会问“我们的 controller 放在哪里”这种问题，因为模板已经把答案写死在生成结果里了。
5. 实操中容易踩的六个坑
5.1 一次性塞入整个仓库上下文
刚开始用模板时，我总会加一句“先通读整个项目再回答”。结果要么上下文窗口直接爆掉，要么模型在无关文件上浪费了大量注意力。
现在我的模板只会指定必要文件的读取路径，而且明确写出“不要读整个 docs 目录，只读 README 开头 200 行和架构文档”。主动裁剪上下文是模板设计里必须做的功课，把模型当检索工具用，是效率最低的姿势。
5.2 命令写得太短，模型靠猜补全
有些同事喜欢把模板压缩成“你是资深工程师，帮我审查代码”，以为越简洁越尊重模型。实际体验正好相反，越简短越容易让模型把隐含规则脑补成它熟悉的那套套路，而非你这套。
我试过同一个模板的长版本和短版本。短版本给出的意见明显更“通用”，很多都是教科书写过的泛泛建议；长版本因为约束清晰，给出的意见更贴合项目里的真实上下文。所以模板不是越短越好，而是该长的长到位，该省的省干净。
5.3 一个模板套所有项目
有一次我把重构模板从单体仓库直接搬到微服务仓库，结果它按单体思维把所有服务全列了一遍。这不是模型变笨了，而是模板里的边界声明和项目结构说明都不再用。
我现在给模板加入项目特性变量，比如“本次操作只允许影响的服务名列表”，把项目间的差异显式外置。每次使用前花十秒填这些变量，比让模板自己猜安全得多。
5.4 输出格式飘忽不定
同样一个模板，今天它输出五个段落，明天它输出三个小节，后天干脆用表格。一开始我也觉得没有大问题，直到我发现自己在解析格式上花费的时间越来越多，而且模型会漏掉我要求的字段。
解决办法很粗暴：在模板里指定固定输出骨架，并且每个字段都给出短语级别的措辞示例。模型对具体格式的服从性比对抽象描述的服从性高一个量级。格式稳定以后，后续结果对比、自动检查、团队流转都方便许多。
5.5 模板本身出现回归
模板也是代码，也需要版本管理。我见过同事更新模板后忘记同步给团队，结果一半人还在用旧模板干新活，产出一团糟。
我的做法是把整个模板目录放在 git 仓库里，每次修改模板都像提交代码一样附带变更说明，并在文件头部标注“最后更新日期和变更摘要”。这样任何一条命令的使用结果出了问题，都可以通过 diff 模板定位是哪个约束变化导致的。
5.6 有了模板就放弃人工审查
这是最危险的心态。模板提高的是 AI 行为的稳定性和可预测性，不代表它突破了自己的能力边界。凡是涉及支付、权限、用户数据、生产环境的改动，我依然要求有人工确认环节。模板里专门写了一条“遇到这类改动必须停顿，等人类决策”的铁律。
6. 把模板放进团队工作流的成熟提速经验
6.1 从个人仓库到团队共享库
我最早是个人自用，后来团队里两个人加入，再后来整个小组都开始用。这个过程中最重要的转变是把模板从“个人笔记”改成“团队接口”。团队共享模板需要描述字段更完整、参数命名更规范、边界声明更保守，因为每个人对指令的理解方式都不一样。
我会在模板库里放一个 README，写清楚每个模板的适用场景、调用方式和典型成功案例。新成员看到的不再是一堆格式不一的 markdown 文件，而是一套有说明、有例子的工具集。
6.2 为高风险操作设定降落伞
模板里必须有“不能做什么”的硬性条款，尤其在涉及生产变更时。比如我会在重构模板里写：“如果某项操作会让已有测试从一个通过状态变成失败状态，禁止继续执行，必须停下来解释冲突点并等待决策。”这类降落伞条款让模型在高风险区域自动踩刹车，而不是莽撞地制造事故后让你去收拾。
6.3 用执行成功率来迭代模板
判断模板好不好用，不要凭感觉。我给模板内置了隐性验收清单，每次执行结束后记录该次任务是否一次性通过。统计一段时间后会发现，修改类模板的执行成功率普遍低于审查类模板，原因是修改类模板对边界定义的要求更高。
基于这个观察，我会在修改类模板里更详细地展开负面约束，并添加“范围变更前必须先汇报”的规则。这个迭代方式听起来机械，但确实能用数据驱动的方式让模板越改越好用。
6.4 任何模板操作都必须可回滚
即使模板做得再完善，我也坚持在跑批量操作前让操作对象处于 git 可控状态。模板里有一句固定规则：“执行修改之前，先运行 git status 确认工作区干净；如果不干净，不做任何改动，先报告情况。”
这不是推卸责任，而是要保证每次试错都能回滚。模型的判断力再强，也只是把概率压低了，不等于零风险。模板的真正价值体现在：当你需要回滚时，它的结构化输出能让你迅速定位改动并干净地撤掉。这不是约束，而是一种对安全底线的尊重。
最后：我对 template 这件事的真实体会
尝试了这么多，我最深的体会是：claude-code-templates 不是一个“写好了就能躺平”的魔法文件，而是一种持续进化的工程实践。我最开始以为自己在给 AI 写指示，后来才发现我是在给团队里每一个将来要跟 AI 协作的人铺路。模板写得越具体，AI 越可靠；模板更新得越勤，团队踩坑的次数越少。
现在每次提交模板改动，我都觉得比提交代码还谨慎。因为代码错了只是一次线上问题，模板错了却可能误导 AI 在一周里反复重复同一种错误。这个观察让我养成了一个习惯：每个季度末翻一遍常用模板，找一个执行成功率最低的模板拆掉重写。这件事没有终点，但它是我目前能找到的、让 AI 协作产出稳定高质量的最优解。
