1. 先搞清楚：Claude Code模板解决的是什么问题
这段时间我把 claude-code 当作日常开发的主力帮手来用，越用越发现一个道理：真正让 AI 产出稳定质量的，不是你问得多巧妙，而是你有没有一套固定的 templates。说白了，模板就是你提前把项目规范、代码风格、审查标准、输出格式这些东西，用一套可复用的提示词结构固化下来，让每次和 AI 的会话都站在同一个起跑线上。
它不是什么玄学，就是一份写给 AI 看的"入职手册"。新人进组要看规章制度，AI 进入你的代码库也一样。没有这份手册，它每次都是"自由发挥"，而自由发挥的结果就是：时好时坏、时详细时敷衍、时而直接改文件时而又只给你一段代码让你自己粘贴。如果你也遇到过这些问题，这篇文章就是为你准备的，不管你是刚上手 claude-code 的新人，还是已经在项目里深度使用它的老手，看完之后都能自己动手写出一套顺手的模板。
1.1 没有模板时，为什么每次都像开盲盒
先复盘一个真实的场景。你让 claude-code "给用户模块加一个导出功能"，没有模板的情况下，它的表现通常是这样：第一次，它很兴奋地给你写了一大段完整代码，附带洋洋洒洒的说明，改了三个文件；第二次，同样的问题，它只给你核心函数，告诉你"其余部分自行脑补"；第三次，它甚至直接拒绝了，说"这个功能涉及数据权限，我不能贸然改动"。
为什么会这样？因为 AI 每句话都在做"续写"这件事。它对你项目背景的理解，完全依赖当前会话里你能提供多少上下文。你这次没说数据库表结构，它就猜一个；你这次没提错误处理规范，它就用自己的默认套路。更麻烦的是，claude-code 这种终端工具是会真实读写文件的，它一旦猜错，改出来的代码可能比不改还糟糕。
还有上下文窗口的问题。聊到第 20 轮的时候，它可能已经忘了你最开始说的"不要动 migrations 目录"这个要求。你说"继续"，它继续了，但是按它自己理解的"继续"在继续。模板存在的价值，恰恰就是把最关键的约束从对话里抽离出来，变成每轮都稳定生效的"上下文常量"，而不是靠你一遍遍重复。
1.2 模板的构成：它到底在约束什么
很多人以为模板就是一段长长的提示词，其实不对。一个合格的模板，至少包含五层内容：角色定义、任务描述、约束条件、输出格式、验收标准。这五层各有各的用途。
角色定义解决"你是谁"的问题。让 AI 知道自己是"资深 Python 后端工程师"还是"熟悉 NestJS 的架构师"，它的用词、关注点会完全不同。任务描述解决"干什么"的问题，这块要写得像一份清晰的工作简报。约束条件是模板的核心，相当于项目的"红线"，比如禁止修改哪些文件、必须遵守哪些命名规范、依赖版本锁定在什么范围。输出格式则决定了 AI 返回结果的样子，是要表格、代码块还是纯文本的改动清单。验收标准更关键，它告诉 AI 什么时候算"干完了"，很多情况下 AI 交出来的东西你觉得不行，不是它不会做，而是你压根没告诉它什么样的结果才算合格。
这五层内容在 claude-code 里，通常放在项目根目录的CLAUDE.md文件里，它会被自动加载进每次会话。也可以按任务拆成多个独立模板文件，在需要的时候通过自定义命令调出来。记住一个原则：模板不是靠华丽的词藻说服 AI，而是靠清晰的结构减少 AI 的猜测空间。
2. 哪几类模板最值得先写
说了那么多理论，落到实际，究竟哪些模板的性价比最高？我自己的经验是：先写四个。代码生成模板、重构模板、调试排查模板、代码审查与提交信息模板。这四个覆盖了日常开发 80% 以上的 AI 协作场景，而且每个都能在写完之后立刻看到效果。
2.1 代码生成模板：解决"看起来对但不一定能跑"的问题
代码生成是 claude-code 最基础的能力，但也是翻车率最高的场景。问题不在 AI 不懂写代码，而在于它默认按"最一般的情况"来写，不考虑你项目的实际情况。一份好的代码生成模板，要把这些"实际情况"全部钉死。
我给自己的项目写的模板长这样：
你是一个熟悉 Python 3.12 和 FastAPI 的后端工程师，代码风格遵循项目现有代码。 任务：根据下面的需求描述，完成代码实现。 约束条件： 1. 只允许修改 src/app 目录下的文件，禁止改动 migrations、tests/fixtures、配置文件。 2. 使用项目已有的数据库会话管理方式（见 src/app/db.py），不得自行创建新的连接池。 3. 所有新增函数必须包含类型注解和 docstring，docstring 要写明参数含义和返回值。 4. 错误处理统一使用 src/app/errors.py 中定义的异常类型。 5. 依赖新增必须显式标明，并在完成后列出需要 pip install 的包名和版本。 输出格式： 1. 先给出 200 字以内的实现思路说明。 2. 再用代码块列出新增或修改后的完整文件内容。 3. 最后用表格列出需要更新的测试用例。 验收标准： - 代码能通过项目现有的 ruff 检查。 - 所有新功能都有对应的单元测试。 - 不改变既有接口的对外行为。你发现了吗，这个模板几乎没有"请帮我"这样的礼貌用语，全部是"规则"。它告诉 AI 的不只是"写什么"，更是"在哪里写、按什么风格写、写完怎么证明"。实测下来，加上这个模板之后，AI 生成的代码基本能做到开箱即用，偶尔有遗漏，也是在小细节上，不会出现"改了不该改的文件"这种灾难性事故。
2.2 重构模板：让改动范围和风险敞口透明化
重构比新写代码更危险，因为它的核心是"行为不变"。AI 很容易在重构过程中顺手"优化"掉一些看似多余实则关键的逻辑。对付这种情况，模板里必须强调一件事：先列计划，再动手。
我的重构模板会明确要求 AI 分四步走：
你是项目的老开发，非常熟悉当前代码库的历史演进。 任务：重构 {模块名}，目标是把业务逻辑和基础设施解耦。 流程要求： 1. 第一步：先梳理该模块当前的所有调用方，列出影响面清单，包括被谁调用、调用方式是什么。 2. 第二步：给出重构方案，用 400 字以内说明，重点说明每个步骤如何保持对外行为不变。 3. 第三步：在得到我的确认后，才开始修改代码。 4. 第四步：每完成一步重构，运行一次项目测试，并把测试结果作为进度汇报的一部分。 红线： - 禁止顺手修改与本次重构无关的代码。 - 禁止移除任何在代码库中仍被引用的函数或变量，即使你认为它"没用"。 - 如果发现某处逻辑无法在不改变行为的前提下重构，停下来向我说明原因，而不是强行改写。这个模板之所以有效，是因为它把"重构"从一道问答题变成了一套流程。AI 不再被要求一次性交出结果，而是被要求先展示计划和风险点。我遇到过很多次这样的情况：AI 在第一步就发现某个模块有六个外部调用方，远超我最初的估计。如果没有这个流程，它可能就直接开干了，改完之后六个调用方崩了五个。
2.3 调试排查模板：把"猜"变成"查"
调试是 AI 最容易"自信地胡说"的领域。你贴上一段报错，它就开始猜：可能是这个问题、可能是那个问题、你试试这样改、你再试试那样改。这种盲猜式的调试，运气好能蒙对，运气不好就是浪费时间。
调试模板要做的，就是禁止 AI 猜测，强制它按可验证的方式排查：
你是经验丰富的系统调试专家。在给出任何结论之前，必须先完成信息收集。 排查流程： 1. 列出你需要的所有信息：完整报错堆栈、相关代码片段、运行时环境版本、最近变更记录。信息缺失时，明确提问，而不是假设。 2. 基于已有信息，给出至少 2 个可能的假设，并为每个假设说明"如果这个假设成立，那么什么现象应该被观察到"。 3. 针对每种假设提出具体的验证方法：查看日志、打印中间变量、编写最小复现脚本。 4. 只有验证结果支持某个假设时，才给出修复方案。 5. 修复完成后，要求 AI 解释"这个 bug 为什么会导致原来的现象"，确保它真的理解了问题本质。 禁止事项： - 禁止直接输出"可能是 xxx 问题"而不给出验证依据。 - 禁止在未确认根因的情况下给出代码修改。 - 禁止把"试试把版本升级一下"作为唯一的解决方案。这个模板用起来最明显的感受是：AI 开始像一个正常的工程师在跟你对齐信息，而不是一个算命先生。有一次排查一个偶发超时问题，它按模板先问了"这个现象是随机出现还是特定接口才出现？最近有没有部署过新版本？"这两个问题直接帮我定位到了问题方向，整个排查时间缩短了一半。
2.4 代码审查与提交信息模板
代码审查模板的价值在于"统一输出"。每个人痛点不同，有的希望 AI 重点看 bug，有的希望它重点看性能。你可以在模板里定制自己的关注维度。我常用的审查模板长这样：
你将以下面的标准审查我提交的代码 diff。 审查维度（按优先级排列）： 1. 正确性：逻辑是否错误、边界条件是否处理、并发安全是否有隐患。 2. 安全性：是否有注入风险、敏感信息是否泄漏、权限校验是否完整。 3. 可维护性：命名是否清晰、函数是否过长、重复代码是否明显。 4. 性能：是否存在明显的低效查询、N+1 问题、不必要的大对象复制。 输出格式： - 每个问题用表格行展示：严重级别（阻断/建议/疑问）、问题位置、问题描述、修改建议。 - 全部问题列出后，用 3 句话总结这次代码的整体质量。提交信息模板就简单多了，它更像一个格式约束器。我会要求 AI 按<type>(<scope>): <subject>的格式生成提交信息，并附上变更原因。这种模板特别适合团队协作，因为每个人 AI 生成的提交信息风格都保持一致，看 git log 的时候不用再费劲切换脑回路。
3. 手写一套模板的全过程
光看别人的模板，如果不自己动手，还是体会不到其中的门道。下面我就拿一个真实场景，完整走一遍从零写模板的流程。这个场景是：我要让 claude-code 帮我维护一个内部工具库的 API 文档。
3.1 第一步：先定义输入输出，而不是先写提示词
大多数人的错误是上来就写"请你帮我写文档"，然后一顿猛输出，结果 AI 给的文档根本不是你想要的。正确的顺序是，先想清楚三个问题：这个模板接收什么输入？输出什么产物？用什么标准衡量产物合格？
以"生成 API 文档"这个任务为例。输入是：某个 Python 模块的路径、函数签名、现有 docstring。输出是：一份 Markdown 格式的 API 参考文档，包含函数列表、参数说明、返回值说明、使用示例。衡量标准是：每个公开函数都被覆盖到，参数说明和签名一致，示例代码可以直接复制运行。
想清楚之后，模板的任务描述部分自然而然就有了方向。它不再是笼统的"生成文档"，而是精确的"从指定模块提取全部公开函数，按项目统一的文档格式输出"。这个步骤看似简单，实际上决定了整个模板的质量上限。输入输出都不清楚，后面写的约束条件就是无根之萍。
3.2 第二步：约束条件要"可验证"，不要"可感受"
写约束条件最容易犯的毛病，就是写一堆听起来正确但实际上 AI 无法自我检查的话。比如"代码要高质量"、"文档要清晰易读"、"保持代码整洁"。这些话都对，但 AI 没办法拿着尺子量一下"到底算不算高质量"。
可验证的约束长什么样？以文档任务为例，我写了这么几条：
- 只提取
src/mylib/下的公开函数（不以_开头的函数）。 - 每个函数必须包含三层说明：功能描述、参数表（参数名/类型/是否必填/含义）、返回值说明。
- 使用示例必须调用真实的函数签名，伪造的函数名和参数会导致示例直接判负。
- 如果函数没有 docstring，根据代码逻辑补充，并在文档中用"根据代码推断"标注。
你看，"不以_开头"就是一个函数能否被纳入文档的明确判据。AI 在代码里扫一圈，符合条件的就写进去，不符合的就不写，不存在灰色地带。而"必须包含三层说明"则规定了文档的结构，AI 交出来的东西可以逐项核对。写约束的时候，你可以在心里模拟一遍：如果我是 AI，我能不能准确判断自己有没有违反这条？如果不能，就说明这条约束需要改写得更加具象。
3.3 第三步：给一到两个 few-shot 范例
文字描述再多，也不如一个现成的例子来得直观。在模板末尾附上一小段"示例输出"，能让 AI 的输出风格和你的预期迅速对齐。这一步很关键，因为 claude-code 的续写特性会强力地模仿你给出的示例格式。
给文档模板配的示例大概是这样的：
示例输出片段： ### `calculate_discount(price: float, percent: float, *, rounding: bool = True) -> float` 计算折扣后的价格。 参数： - `price` (float)：原始价格，必须大于 0。 - `percent` (float)：折扣百分比，取值范围 0 到 100。 - `rounding` (bool, 可选)：是否对结果四舍五入，默认 True。 返回值：折扣后的价格（float）。如果 `percent` 为 0，返回原始价格。 示例： ```python from mylib import calculate_discount calculate_discount(100.0, 20.0) # 80.0这个示例的价值在于，它一次性地展示了层级结构、参数描述的格式、返回值说明的方式以及示例代码的写法。AI 看到这个，基本就能猜到"哦原来你要的是这种风格的文档"。这段示例我大概只花了五分钟写，却省下了我跟 AI 来回纠正格式的大把时间。 ### 3.4 第四步：测试、迭代、版本化 新模板写完不要直接投入到正式任务里，先在项目里挑一个小模块试运行一遍。我通常会对比三个东西：产出结果的格式是否和示例一致、覆盖范围是否符合预期、有没有出现模板没考虑到的新情况。 第一次测试，AI 把 docstring 里原有的 deprecated 标注删掉了。第二次测试，它在参数表里手动加了一列"默认值"，而我的示例里没有这列。这些偏差都需要在模板里补充说明，要么加一条"保留原有的 deprecated 标注"，要么加一条"参数表不允许新增示例之外的列"。 这里有一个实践细节：把模板文件纳入 git 管理，每次修改都提交一次，写清楚变更原因。比如 `docs: 补充默认值列说明，防止AI擅自新增格式`。时间长了，你的模板本身就是一份项目文档，你能看到它的演进历史。而且在 claude-code 的会话里，你也可以直接 `/git log` 查看模板的修改记录，方便回退到某个稳定版本。 ## 4. 模板用起来之后的常见坑 模板不是写出来就万事大吉了，用的过程中坑还挺多的。我把这段时间踩过的、帮别人排查过的问题集中整理一下，基本上每一条都能在模板落地的头两周遇到。 ### 4.1 模板太长，效果反而变差 很多人觉得模板越长越详细越好，这是一个误区。我见过有人把 CLAUDE.md 写成 2000 行的"百科全书"，结果 AI 的行为反而变得畏手畏脚，什么都不敢做。原因是上下文的注意力分布是有限的。当模板里塞了太多规则之后，模型会"过拟合"到某几条词频最高或位置靠前的规则上，其他的要么忽略、要么在几个约束之间犹豫不决。 我的经验是，全局模板（每个会话都加载的）控制在 100 行以内，集中写项目最核心的红线和风格规范。任务级的专用模板控制在 50 到 80 行，一次专注解决一件事。如果你有很多任务模板，不要全部堆进 CLAUDE.md，而是用斜杠命令的方式，让它们在需要的时候被调用。比如我定义的 `/refactor` 命里只包含重构模板的内容，平时不加载，只有输入这个命令才触发。 ### 4.2 约束条件互相打架 另一类高频问题是约束自相矛盾。最典型的就是同时要求"代码简洁"和"所有函数都要有详细注释"，这两个目标在 AI 眼里是冲突的。它可能为了简洁砍掉注释，也可能为了注释凑出一堆废话。类似的对子还有："不要修改无关代码"和"顺手修复你发现的小问题"。 解决方式是给约束定优先级。我会在模板里直接写"如果遇到冲突，按以下顺序执行：安全性 > 正确性 > 可维护性 > 性能 > 代码精简"。这样 AI 在遇到左右为难的情况时有一个明确的决策依据。你甚至可以故意在模板里放一条"本模板的约束以优先级顺序为准，后出现的约束不得覆盖先出现的约束"，给 AI 一个处理矛盾的原则。 ### 4.3 工具调用和权限范围 claude-code 是能执行命令、读写文件的，这意味着模板约束的不只是"说什么话"，还包括"能碰哪些地方"。我在这上面吃过亏：模板里只写了"不要改 migrations 目录"，结果 AI 把项目里的一个小工具脚本删了，它认为那是"无关的临时文件"。 现在的做法是，模板里明确一个"允许操作区"和"禁止操作区"清单。允许区写清具体路径，禁止区也要写清具体路径，并且在模板开头就声明一条铁律："对允许区之外的任何文件系统变更，都必须提前征求确认，等待用户批准后才能继续。"此外，涉及执行 `git` 命令、`pip install` 这种有副作用的操作，我都会在模板里要求 AI 先说明将执行什么命令、目的是什么、可能的影响是什么。这套机制加进去之后，误操作的概率低了很多。 ### 4.4 模板需要持续维护，不是一劳永逸 模板有效期这事容易被忽略。项目换了数据库、升级了框架、调整了目录结构，模板里的约束条件分分钟过期。最典型的例子是，我有个模板要求"新增代码使用项目原有的 logger"，后来项目迁移到了新的日志方案，旧 logger 已经废弃，但模板里没更新，AI 按旧规范生成了一堆即将被淘汰的代码。 所以每隔一段时间（我是每个迭代周期结束的时候），把模板过一遍，问几个问题：里面提到的目录结构还存在吗？引用的工具链还是当前版本吗？示例代码还能跑通吗？这个维护动作花不了十分钟，但能避免模板从"助力"变成"阻力"。另外一个值得养成的习惯是，当你发现 AI 反复在某类约束上犯错时，不要每次都手动纠正，而是把它写进模板，让模板跟着实际问题一起进化。 写到这里，我想强调一点：模板最核心的价值不是约束 AI，而是逼着你自己把需求想清楚。很多时候你写不出好模板，不是不懂提示词技巧，而是根本没想明白自己要什么。我在给 claude-code 写模板的过程中，对自己项目的理解反而加深了不少。如果你手头还没任何模板，今晚就可以挑一个折腾你最久的场景，按这篇文章的五个构成要素写一版，遇到问题再回来对照常见的坑，慢慢你就会有自己的一套体系。
