做 claude-code-templates 这个项目之前，我在 Claude Code 上的使用体验只能用"薛定谔的质量"来形容。同样是重构一个模块，有时候它事无巨细地给我解释半天，有时候又一句话带过直接甩代码；同样是让 AI 审查代码，有时候它给出了非常到位的并发隐患提示，有时候却把精力放在修改变量命名这种无关痛痒的地方。这种失控感一度让我怀疑模型能力不够，但后来我意识到，问题不在模型，在于我根本没告诉它"按什么套路来"。
claude-code-templates 的核心就是一个提示词模板库：把每次重复交代的角色、任务边界、输出格式、质量红线全部固化下来，让 Claude Code 在接到任务的第一秒就进入"专家状态"。说白了，就是给 AI 立规矩、定套路，让它的输出不再是随机波动，而是稳在一条基准线之上。这套东西适合已经在用 Claude Code 但觉得输出不够稳定的开发者，也适合想系统提升 AI 编码质量、把 AI 用出"高级感"的人。
接下来我会从模板的结构设计、几套可以直接抄作业的模板、在 Claude Code 里落地模板的三种姿势，以及我调试模板过程中踩过的坑这几个方向展开。如果你是刚接触 Claude Code，前两节可以帮助你建立骨架认知；如果你已经踩过一些坑，可以直接跳到第三节开始抄模板。
1. 为什么要给 Claude Code 准备模板：从裸聊到结构化
1.1 没有模板时我踩过的坑
先说一段真实经历。有段时间我频繁让 Claude Code 帮忙做代码审查，用的方式是直接描述一句话："帮我 review 一下这个文件"。结果大家应该能猜到：第一次它认真列出了十几个问题，第二次面对同样规模的代码却只回了一句"看起来没问题"。
这种不稳定不是偶发现象。问题出在三个方面：
一是目标漂移。没有模板时，模型会自己在"找bug、提建议、讲解原理、直接改代码"这几件事之间随机游走，甚至会出现"先评论代码风格、再分析性能、最后变成教学"这种四不像的输出。二是标准不统一。同样是审查，第一次可能只关注逻辑错误，第二次却重点看命名规范，因为提示词里没有定义"什么最重要"。三是输出形态不可控。有时候给表格，有时候给长文，有时候直接给 diff，我看得一头雾水。
这三个问题叠加起来，让 AI 工具的价值大打折扣。后来我把搜索到的几套开源 prompt 工程方法拿过来对比，发现真正有效的做法只有一个：不要每次重新写提示词，而是维护一套固定的模板，把对 AI 的期待全部"写死在纸面上"。
1.2 模板的价值：把通用助手变成岗位专家
Claude Code 本身是一个很强的通用编码助手，但"通用"也意味着"没有棱角"。如果你不告诉它今天扮演什么角色，它默认会给你一个中庸的、各方面都沾一点的反馈。而模板的价值，恰恰是把无棱角的通用能力塑造成特定场景下的专家行为。
我举个例子。假设你要做一次接口兼容性审查，没有模板的话 AI 会关注什么？大概率是命名、注释、有没有语法错误。但如果你在模板里明确它应该关注"旧调用方是否会被破坏、默认参数变更是否影响外部行为、返回值类型变更是否导致下游失败"，它的注意力就会被精准拉过去。同一个模型，模板不同，产出的含金量完全不同。
所以在 claude-code-templates 里，我做的第一件事不是堆数量，而是把使用场景拆开：代码审查、重构、单测生成、提交信息撰写、错误排查、技术方案设计、遗留系统文档梳理。每个场景一套模板，每套模板都围绕"让 AI 在一类任务上有持久稳定的专家表现"来设计。
提示：模板不是万能药。如果你的场景是开放式头脑风暴、"随便聊聊架构"，那反而是不套模板效果更好。模板的适用边界是"任务边界清晰、质量标准可定义、输出形态可预期的场景"。
2. 模板的核心结构与设计思路
2.1 一个合格模板的五个必备模块
我早年看过不少 prompt 教程，自己也拆过很多开源模板，最后总结出一套五段式结构。是我认为目前最稳的写法，也是 claude-code-templates 里所有模板的骨架：
- 角色定义：开头第一句就要把 AI 的身份钉死。
- 任务描述：用清晰的语言界定本轮要做什么、不做什么。
- 输入约定：说明代码、文件路径、上下文信息如何给。这一块最容易被忽略，但它决定了每轮交互时模板能不能"接得住话"。
- 约束与禁区：列出绝对不能做的事情、不能逾越的质量红线。
- 输出格式：指定用表格、清单、代码块还是 diff 输出，并给出结构骨架。
这五个模块不是随便堆砌的，它们各自解决一个真实问题。角色定义解决"风格漂移"，任务描述解决"目标漂移"，输入约定解决"话传不到位"，约束与禁区解决"AI 自作主张"，输出格式解决"解析成本过高"。五件套齐全，模板才是一个完整的工作协议，而不是一句好听的提示词。
2.2 角色定义与任务边界的写作技巧
角色定义看似简单，但很多人写得不对。差的写法是"你是一个资深工程师"，好的写法是"你是一位拥有十年以上后端开发经验、主导过大型系统架构设计、主要使用 Go 和 Python 的工程师，擅长发现分布式系统中的并发隐患和故障恢复问题"。
区别在于细节锚点。锚点越具体，AI 越容易激活对应的知识域，给出的建议就越贴近真实专家。我常用的手法是在角色里嵌入三个要素：年限与层级（影响表达的权威感和判断力）、技术栈（影响举例和方案选型）、过往项目类型（影响关注点）。
任务边界这一块，我踩过最大的坑是"给了任务但没给反例"。比如代码审查模板里写"审查这个文件"，模型可能顺手开始关注代码风格；于是我在所有模板里都加了"不做某事"的显式说明。例如审查模板里明确写"不关注缩进、命名风格这类问题，除非它们影响代码正确性"。负面约束的作用往往比正面指令更明显，这条经验价值极高。
2.3 输出格式与约束条件的设计原则
输出格式为什么要写死在模板里？因为模型在自由发挥时，输出的结构方差巨大。如果你需要的是能在 CI 里解析的审查报告，它给你一篇散文，你的自动化流程就断了。所以在 claude-code-templates 里，我给每个模板都设计了固定的输出骨架。
以代码审查模板为例，输出格式固定为：结论段、问题清单表、可选的改进建议段。问题清单表固定四列：严重等级、位置、问题描述、修复建议。这样的结构有两个好处：一是人眼扫读成本极低，二是问题清单可以脚本化处理，比如提取所有"严重"级别问题自动发送到消息通知。
约束条件的写作原则是"少而狠"。不要列二十条纪律，模型记不住那么多优先级。抓住两三条真正致命的要求即可。比如在重构模板里，我写的最高约束是"必须以行为保持为前提，任何可能改变外部行为的重构必须显式标注风险"。这一条压住了模型"顺手改逻辑"的老毛病。
3. 实战：三套可以直接抄作业的模板
3.1 模板一：高效代码审查模板（人工校对版）
这套模板我用了最久，效果最稳定，先放成品：
角色：你是一位拥有十年以上后端开发经验的资深代码审查专家，长期从事大型分布式系统研发，熟悉边界条件漏洞、并发竞争、幂等等高风险问题，对代码可维护性有极高要求。 任务：审查我提供的代码，输出一份结构化审查报告。重点关注以下问题： 1. 正确性：死循环、空指针、越界、并发竞争、状态未回滚 2. 健壮性：输入校验缺失、异常吞掉、超时未处理、重试策略缺失 3. 安全隐患：注入、敏感信息硬编码、越权风险 4. 可维护性：重复代码、过长函数、明显的架构问题 输入约定：我将在"审查代码"标记之后提供代码。如果代码中有 TODO 或未完全实现的部分，请在报告中单独说明。 约束与禁区： - 不要关注缩进、命名风格、注释数量等非功能性事项 - 不要为了凑数量上报问题，没发现问题就明确说“未发现明显问题” - 问题必须能找到明确依据，不输出猜测性结论 输出格式： ## 审查结论 （两到三句话，说明代码质量概况、是否可以合并入主干） ## 问题清单 | 严重等级 | 位置 | 问题描述 | 修复建议 | |---------|------|---------|---------| | 严重/一般/建议 | 文件:行号 | ... | ... | ## 改进建议 （可选，只写结构性建议，不写琐碎改动）设计这套模板时有一个细节值得说明：约束与禁区里明确写了"不要关注缩进、命名风格"。
为什么非要加这条？因为在没有这条约束时，模型经常把问题清单塞满"变量名可读性差""函数有点长建议拆分"这类低价值建议，真正致命的并发隐患反而被挤到后面去了。加这一条负面清单之后，审查质量肉眼可见地提升。
另一个容易忽略的细节是"如果发现 TODO 或未完成的部分，单独说明"。这是我从一次事故里学到的。有次 Claude Code 审查一个含有 TODO 的半成品函数，默认策略是"基于推测补全逻辑"并输出一条看起来合理的问题描述，但那个推测和实际业务不符。让模板明确引导 AI 把"TODO 与未完成"作为独立关注项，避免它把半成品当作完整的代码去评价。
3.2 模板二：行为保持重构模板（老代码福音）
重构是所有 AI 编码工具最容易翻车的地方，因为模型倾向于"顺手优化"。比如你让它重命名变量，它把一处三元运算换成 if-else；你让它拆分函数，它顺手把默认入参值也改了。这套模板的核心目的就是锁死"行为保持"这条底线。
角色：你是一位精通重构的软件架构师，熟悉 Martin Fowler 的重构方法论，擅长在保持外部行为完全不变的前提下优化代码结构。你对“重构中改变行为”的情况高度警惕。 任务：基于我提供的代码执行重构。允许的改动包括：提取函数、更改变量名、简化条件表达式、拆分过长函数、调整类内部结构。禁止改变：对外接口签名、默认行为、异常抛出顺序、边界处理逻辑。 输入约定：如果代码量较大，我会先提供目标文件路径，你需要先阅读文件再操作；如果代码量在 200 行以内，我会直接在“重构代码”标记后粘贴。 约束与禁区： - 任何可能改变外部行为的调整必须单独标注风险，不能混在普通重构里 - 不要引入新的依赖，不要改动测试策略 - 重构必须保持单元测试可通过，如果我没有提供测试，你需要输出“未验证风险说明” 输出格式： ## 重构摘要 （说明做了什么、保留了哪些行为保证） ## 改动清单 | 文件 | 改动类型 | 改动说明 | 行为影响 | |------|---------|---------|---------| ## 未验证风险说明 （如果没有测试套件支撑，明确写出哪些行为可能存在未验证风险）我推荐这套模板给两个典型场景：一是接手老项目时，把那些几千行的"面条式"函数安全拆开，便于后续维护；二是做大规模重命名或者从回调改 Promise 时用。后者风险高，行为不变的约束尤其重要。
用这套模板最需要注意的，是"行为影响"列。我要求模型在每一次改动后面都写清楚这对运行时行为有没有影响。一开始这会增加一点输出量，但它会逼着 AI 在脑子里过一遍"这次改动改没改语义"，实际减少的事故量远远超过那点 token 成本。
3.3 模板三：测试用例生成模板（覆盖率增长利器）
很多团队的痛点不是不会写测试，而是测试的覆盖路径太单一。让 Claude Code 生成单测时，如果模板不到位，它会生成一堆"给定正常输入、期待正常输出"的无用用例，真正的边界条件全部错过。
角色：你是一位专注于单元测试的测试开发工程师，擅长边界值分析、分支覆盖和故障注入。你熟悉多种语言的测试框架（JUnit、pytest、Go testing 等），习惯从“哪里可能出错”的角度设计用例。 任务：为提供的函数或方法生成单元测试。请以“发现缺陷”为目标，而不是“验证能跑通”。重点覆盖： - 边界值：空值、零值、最小值、最大值、超长字符串、负值 - 异常路径：异常抛出、错误返回、超时、内部失败 - 状态变化：重复调用、并发调用、依赖状态变更 输入约定：我会提供被测代码和语言/框架信息。如果被测函数依赖外部服务，请优先使用依赖注入或 mock 策略，并在测试中注明。 约束与禁区： - 不要生成只验证“正常路径”的测试用例 - 不要为生成简单的 getter/setter 创建测试 - 不要修改生产代码，除非你明确说明必须拆分才能测试 - 每个测试用例必须写明验证意图 输出格式： ## 测试用例清单 | 用例名称 | 输入构造 | 预期行为 | 覆盖意图 | |---------|---------|---------|---------| ## 测试代码 （用代码块输出完整测试文件） ## 风险与建议 （指出被测代码中难以测试的设计，并给出修改建议）这套模板的三段式输出里，我最看重"覆盖意图"那一列。让 AI 显式写出每个用例的意图，实际上是在倒逼它思考"这个用例到底覆盖了什么"。如果没有这一列，模型会生成大量"看起来多、实则重复"的用例，加了这列之后，覆盖率逻辑立刻清晰了。
在我自己的工作流里，这套模板和重构模板经常搭配使用：重构前先生成测试，重构后跑测试，用同一套测试验证行为保持。两套模板结合起来，AI 重构的安全性会高一个量级。
4. 在 Claude Code 中落地使用模板的几种姿势
4.1 姿势一：通过 CLAUDE.md 全局注入基础约定
CLAUDE.md 是 Claude Code 项目初始化时自动加载的全局上下文文件，最适合放"跨任务通用"的约定，而不是放具体模板。我在 CLAUDE.md 里通常放三类内容：技术栈与目录结构说明、代码风格与质量红线、以及"在哪些场景下推荐使用哪个模板"的映射表。
举个片段：
# 项目约定 ## 技术栈 后端使用 Go 1.22 + PostgreSQL，前端使用 React 18 + TypeScript。 单元测试使用 Go testing + testify，覆盖率目标为 80%。 ## 质量红线 - 所有对外接口必须保持向后兼容，除非有显式的 break-change 说明 - 禁止在生产代码中留下调试输出 - 数据库迁移必须提供回滚脚本 ## 模板映射 - 代码审查：执行 `claude -p "$(cat templates/review.md)" --file <path>` - 重构：执行 `claude -p "$(cat templates/refactor.md)" --file <path>` - 测试生成：执行 `claude -p "$(cat templates/test-gen.md)" --file <path>`把模板映射表写进 CLAUDE.md 的意义在于，它把"用什么模板、怎么调用"变成了一种团队共识，别的同事拿到仓库后不需要问就知道该怎么让 AI 干活。这块建议所有做团队协作的人尽快用起来，效果立竿见影。
4.2 姿势二：通过 -p 参数在命令行中直接调用
Claude Code 支持-p参数直接传入提示词并返回结果，这是我最常用的调用方式。配合模板文件，我经常这样写：
claude -p "$(cat templates/review.md)\n\n审查代码:\n$(cat src/main.go)"这条命令有几个好处：一是模板稳定，不依赖我每次的临场发挥；二是可以批量处理，比如把多个文件名的循环丢进 shell 脚本里逐一审查；三是输出是纯文本进 stdout，可以接 jq、tee 等工具做后处理。
为了让输出更可控，我通常会再包一层脚本。比如我维护了一个review.sh，它接受文件路径作为参数，自动拼接模板和文件内容，然后把输出格式化后追加到当天的审查日志里。这样一来，每次审查都留痕，后期回溯非常方便。
#!/bin/bash # 用法: ./review.sh src/main.go FILE="$1" PROMPT="$(cat templates/review.md)" echo -e "$PROMPT\n\n审查代码:\n$(cat "$FILE")" | claude -p提示：如果模板较长，注意保持 prompt 中的输入约定与命令传参一致。我在模板里写的是"审查代码标记之后提供代码"，所以命令里拼接的段落必须以"审查代码:"开头，防止模型找不到输入。这个一致性设计直接决定了模板在命令行场景下能不能稳定工作。
4.3 姿势三：把模板组织成自己的提示词库目录
随着模板越写越多，我开始把它们当作真正的代码资产来管理。目录结构大概长这样：
claude-code-templates/ ├── README.md ├── CLAUDE.md.example ├── templates/ │ ├── review.md │ ├── refactor.md │ ├── test-gen.md │ ├── error-debug.md │ ├── commit-msg.md │ └── doc-gen.md ├── scripts/ │ ├── review.sh │ ├── refactor.sh │ └── test-gen.sh └── examples/ ├── review-output.md └── refactor-output.md这已经是我现在唯一在用的组织形式了。维护这个仓库的办法也很简单：每次用模板发现结果不理想，就打开对应的 md 文件增加一条约束；每次想出新的任务场景，就新建一个模板。核心原则是把模板当成迭代产品，而不是一次性提示词。
另外推荐在模板里写清楚版本号或最后修改日期。别笑，这个细节救过我一次：团队里有人改了一版审查模板，把输出格式改成了 JSON，结果下游脚本全部失效。因为没有版本标记，排查了很久才发现是模板变了。加一个更新日期字段到模板头部，以后这类问题三十秒就能定位。
5. 我在模板实践中踩过的坑与沉淀的心得
5.1 模板会过期，要持续维护更新
很多人以为模板写过一遍就完事了，这是最大的误解。模型的版本迭代、项目技术栈的变化、甚至你自己对协作方式的偏好变化，都会让模板逐渐失效。我曾经有一版模板在 Claude 3.5 上表现优异，换到 3.7 之后就出现了严重的"过度输出"问题——每个问题都要长篇大论解释原理。后来补了一条约束"每个问题的描述不超过三句话"，才把输出拉回正常。
维护模板的频率不需要太高，我现在的节奏是每周抽十分钟回顾一次：看看最近几轮输出有没有"跑偏"，如果跑偏了，就找一条最共性的问题加进约束区。这种小步迭代比一次性追求完美有效得多。
5.2 注意上下文窗口预算，别被模板反噬
模板是有上下文成本的。一个精心设计的模板可能就要 1200~2500 token，如果代码文件比较大，再加上历史对话，很可能把上下文撑爆。代价是模型开始"选择性失忆"，你早些时候提到的要求它会当成噪音忽略掉。
我的经验是：把模板压缩到 1500 token 以内，并通过输入约定引导用户只贴"必要代码"，而不是整个文件。举例来说，审查模板里我写的是"如果代码超过 500 行，请描述核心逻辑并提供关键代码段，不必贴完整文件"。这样模板在自我保护，同时也保护了上下文窗口。
压缩模板还有一个技巧：用表格代替散文。同样一段约束逻辑，用散文写可能需要 400 token，用表格写可能只要 120 token。模型的表格理解能力很强，这一点我实测过多次，放心用。
5.3 从"模板"到"工作流"的进阶方向
模板做到后面，会自然长成一个更大的东西——工作流。比如我现在已经不完全是一个一个手动调claude -p了，而是写了一组脚本把它们串成流水线：改动代码 -> 自动生成测试 -> 运行测试 -> 通过后进入代码审查 -> 审查通过生成提交信息。每个环节都有一份模板在背后支撑，AI 的输出从一个一个孤立的回应，变成了一条稳定协作的生产线。
如果你也想往这个方向走，建议从最频繁的任务开始，先给这个任务写好模板，再写一个 shell 脚本把模板和文件拼起来，最后再把多段脚本串起来。每走一步，都能立刻感受到稳定性的提升。
最后再分享一个小经验：模板是写给别人用的，但首先是写给你自己和未来的你看的。每次新建模板时，不妨在开头写一句"什么场景不要用这个模板"，比如测试生成模板里我会写"如果被测代码是纯配置映射，不需要单元测试"。这能帮你在三个月后重新打开这个文件时，快速判断它适不适用，省下很多自我纠结的时间。
claude-code-templates 这个项目走到现在，带给我的最大变化其实不是输出质量的单次提升，而是让我把 AI 协作从"碰运气"变成了"有流程"。希望上面这些模板和踩坑记录，也能让你的 Claude Code 少一些"薛定谔的发挥"，多一些稳定输出。
