前几天把一套自己一直在用的提示词模板整理成了开源项目，姑且就叫claude-code-templates。不是那种随手写两句的“咒语”，而是一整套按场景拆好的、直接能扔进 Claude Code 里跑的规则集。今天不聊概念，直接把这套东西怎么设计、怎么配、怎么用、踩过哪些坑，全部摊开讲一遍。

如果你已经在用 Claude Code 写代码、改 bug，但总觉得它“时灵时不灵”——有时候推理链路很清晰，有时候又像喝多了跟你胡扯；如果你试过在系统提示词里写一堆中文要求，结果输出质量依旧忽上忽下；那这篇就是为了解决这个问题整理的。我会从设计思路讲到完整落地步骤，最后把我自己在团队里推广这套模板时遇到的典型问题一并列出来。

1. 先聊清楚：这个模板集到底解决了我什么痛点

1.1 为什么默认的 Claude Code 会“跑偏”

很多人第一次打开 Claude Code，第一反应是震撼——它可以在终端里直接读代码、改文件、跑测试、提 commit，像一个坐在你旁边的资深工程师。但用几天之后，问题就来了：它太容易被“带偏”。

具体表现为几种情况：

• 让它修一个 bug，它顺手把整个模块的重构方案也给你列出来，改到一半你发现几个业务方法签名全变了；
• 让它写单元测试，它按照自己的审美生成了一批“理想化”测试用例，完全没覆盖项目里真正出过问题的边界场景；
• 让它按照项目的代码风格补功能，它根本不看现有函数是 40 行一个还是 400 行一个，统一按自己的套路写；
• 上下文一长，后边的对话就开始重复此前说过的内容，甚至编造不存在的 API。

这些问题的根源，并不在于模型能力，而在于缺少约束。你给它一个“帮我写个函数”的指令，它就只能根据训练数据里的“平均形态”去写，而不是根据你这仓库里的“实际形态”去写。这就像你让一个技术很强的外包帮你改代码，但没给他看你团队规范、没告诉他哪些是可动区域哪些是禁忌区，他自然按自己的习惯来。

1.2 模板解决的不只是“输出质量”，而是“输出预期”

claude-code-templates最核心的思路，是把每个任务场景的上下文约束提前写好，让 Claude Code 在动手之前，先“看到”它应该遵守的规则、应该输出的结构、应该避开的雷区。模板不是一个固化死的提示词，而是一组分层的规则：

• 全局规则（适用所有任务）；
• 场景规则（比如“写单元测试”和“做代码审查”完全两套规则）；
• 项目规则（针对当前仓库的目录结构、语言风格、不可动模块）。

这三层叠在一起，效果非常明显。我实测下来的感受是：模板更像给模型的一份“公司规章制度”，而不是一句“你好好干活”。你提前告诉它出勤时间、着装要求、汇报格式，它交上来的东西自然就会往合规的方向靠。

1.3 适合谁，不适合谁

说点实话。这套模板最适配的是已经把 Claude Code 当作日常主力开发工具的人，无论你是个人博主写 side project，还是在十几人的技术团队里推进 AI 辅助开发，都值得试一下。

但如果你只是偶尔用命令行问几个问题，没打算把它嵌进日常工作流，那这套模板对你就属于过度设计——你有那个配置时间，不如直接对话里说清楚需求。

还有一个“不适合”：如果你的项目代码风格本来就乱成一锅粥，没有统一的命名规范、没有分层思想、测试覆盖率长期是零，那模板只能帮你约束 AI 的输出，约束不了你已有的代码。建议先把项目本身整理到“基本可读”的状态，再上模板。

2. 模板集的核心设计与模块拆解

2.1 目录结构：一眼看清库里面有什么

先贴一个我整理后的目录结构，方便你先建立整体认知：

claude-code-templates/ ├── README.md ├── templates/ │ ├── unit-test/ │ │ ├── SYSTEM.md │ │ └── examples/ │ ├── react-component/ │ │ ├── SYSTEM.md │ │ └── examples/ │ ├── cli-tool/ │ │ ├── SYSTEM.md │ │ └── examples/ │ ├── code-review/ │ │ ├── SYSTEM.md │ │ └── rules/ │ │ └── security.md │ ├── refactor/ │ │ ├── SYSTEM.md │ │ └── rules/ │ │ └── compatibility.md │ └── commit-message/ │ ├── SYSTEM.md │ └── examples/ └── project_rules/ ├── python_rules.md ├── node_rules.md └── common_rules.md

这个结构看着简单，但每一层都是有讲究的。templates/下每个目录对应一种任务场景，SYSTEM.md是给 Claude Code 读的“角色设定 + 输出规则 + 禁止事项”；examples/是给模型参考的输入输出示范；project_rules/则是跨场景的项目级规则。

重点说下为什么要把examples/单独提出来。模型真正聪明的地方在于少样本学习——你不光告诉它“你要写符合规范的 commit message”，还要给它 2-3 个“好”和“坏”的实例，它才能精确理解你说的规范到底是什么。纯文字描述永远是模糊的，例子的价值就在这里。

2.2 每类模板的定位与适用场景

unit-test（单元测试生成）

这是我个人使用频率最高的一套模板。它的核心规则是：只生成当前文件缺失的测试，不重复已有覆盖；遵循项目里已有的测试框架和命名习惯；不 mock 掉那些真正重要的边界条件。

react-component（React 组件开发）

约束点是组件拆分粒度、Props 设计规范、样式方案的选择。我踩过最深的坑是：Claude Code 经常自作主张给纯展示组件引入状态管理库，模板里就专门写了“禁止引入未使用的依赖”这条。

cli-tool（命令行工具开发）

你让它写一个 CLI 工具，默认情况下它输出的参数解析、帮助文档风格五花八门。这套模板规定死了：使用同一套参数解析库、必须有--help输出、错误提示需要包含修复建议。

code-review（代码审查）

很多人不知道，Claude Code 做代码审查，效果上限很高但下限极低。默认情况下它会陷入“找几个代码风格小问题然后大夸特夸”的温柔陷阱。模板里强制要求按维度输出：正确性、性能、安全性、可读性、可测试性，并且必须按严重程度排序。

refactor（代码重构）

这类模板要把“改动范围控制”写死。核心规则是：重构期间不允许改变现有接口签名、不允许顺手改掉无关代码格式、每步重构后必须跑测试确认绿灯。

2.3 为什么选择“提示词模板 + CLAUDE.md”这套组合

你可能会问：Claude Code 本身就支持项目级记忆（CLAUDE.md），为什么我还要单独搞一套模板集？

我的答案是：CLAUDE.md 管的是项目的“长期底色”，提示词模板管的是每次任务的“临时上下文”。前者解决“这个仓库是什么风格、有哪些规矩”，后者解决“这次我要你按什么格式产出”。两者缺一不可，如果只靠 CLAUDE.md 来约束一切任务，你会发现它越来越臃肿，最后任何指令进来，模型都要先处理一堆无关的规则。

所以我的用法是：把项目相关的长驻规则（依赖管理方式、测试命令、目录约定）写进CLAUDE.md；把任务相关的临时约束放在templates/里，需要时通过@引用或者直接复制进对话。这样既保证了全局一致性，又不至于让每个请求都背负整个项目的大字典。

3. 关键参数与配置解析

3.1 提示词模板的三个核心参数块

我自己在写模板时，不管场景怎么变，都会保证每个SYSTEM.md里包含三个标准块：角色定义、输出规范、红线约束。

角色定义不是简单写一句“你是一名资深工程师”——那是废话。要写的是“你是在 XX 项目上工作了三年的核心维护者，熟悉该项目的全部业务模块和依赖关系”。模型在扮演具体角色时，调用的知识范围和表达方式都会有可感知的差异。

输出规范要尽可能结构化。不是“写清楚一点”这种废话，而是：“先输出改动摘要，不超过 5 行；再列出改动文件清单，标注新增/修改/删除；最后给出测试执行结果。示例见 examples/”。

红线约束是最容易被忽略、但实际价值最大的一部分。比如我在test模板里写了三条红线：

• 不修改被测源码，除非测试本身暴露了真实 bug；
• 不删除已有测试用例，只允许新增；
• 不引入新的测试框架。

这些约束在默认行为下模型大概率不会自觉遵守，但写进模板后，配合 Claude Code 的指令解析能力，几乎能 100% 规避。

3.2 一个合格模板的七条标准（经验总结）

我把踩坑踩出来的经验浓缩成七条，你写模板时可以直接拿来自检：

1. 模板必须给出反面示例，只给正面示例，模型会倾向于模仿句式而不是理解约束；
2. 每条规则都要能“被验证”，比如“不添加依赖”就比“尽量少加依赖”有效得多；
3. 模板长度控制在 150-300 行之间，太短约束不够，太长模型注意力会被稀释；
4. 场景分类宁多勿少，一个“通用模板”远不如 6 个场景模板加起来好用；
5. 格式用列表和短句，模型对列表格式的遵循度远高于长段落；
6. 规则之间不能互相矛盾，比如既让它“保持最小改动”又让它“顺手优化相关模块”，模型会陷入混乱；
7. 每次跑完重要任务后，顺手把失败的输出反馈回模板，让它在实例里多一个反面教材。

3.3 默认输出与模板化输出的差异对比

下面这张表，来自我最近把模板推到团队后的一次实测对比。同一个仓库、同一个任务（给一个用户服务模块补单元测试），模板开与不开差异明显：

表格最后一行其实是最关键的价值指标。模板化不会让你完全不用看 AI 的输出，但能把“核对节奏”从“逐行审”降到“抽查”，这才是它真正的生产力来源。

4. 完整实操：从零搭建一套可复用的模板库

4.1 安装与初始化

假设你已经在自己的项目里初始化好了 Claude Code，现在开始搭建模板库。我的做法是把它作为独立目录放在仓库根目录下，好处是不会污染src/或tests/，也方便后续用 git submodule 或者 vendoring 的方式同步到多个项目。

第一步，先建目录并写入全局规则。创建project_rules/common_rules.md时，我放的是对任何项目都适用的底线要求：

# 通用规则 - 所有生成的代码必须通过现有 lint 检查，如需绕行必须给出理由。 - 禁止发明不存在的标准库 API 或者依赖包。 - 修改文件时默认不改变第 1 至 200 行的既有逻辑，除非任务主诉就是调整该区域。 - 每个代码块后面必须附带最小可验证示例。

这套通用规则会在后面所有场景模板里被引用，属于地基。实测下来，最有用的是第二条“禁止发明 API”——很多 AI 生成的代码看着没问题，一编译才发现调用了不存在的函数。

4.2 手写一个 CLI 工具开发模板并跑通

接下来拿cli-tool模板当示例，完整走一遍。这条模板我用的频率仅次于单元测试模板。

先创建templates/cli-tool/SYSTEM.md：

# 角色 你是一个有五年维护经验的 CLI 工具开发者。你熟悉的语言包括 Python、Node.js 和 Go，但优先使用当前仓库的主要语言。 # 任务输入格式 用户会给出： - 工具名称和功能描述 - 需要支持的子命令列表 - 期望的行为（例如读取配置文件、输出彩色日志） # 输出规范 1. 先输出文件变更清单（新增/修改/删除）。 2. 然后按单文件逐块输出代码，禁止一次性贴出整个目录。 3. 每个文件开头两行注释中说明该文件的职责和依赖。 4. 必须实现 --help 和 --version 参数，格式遵循当前项目的已有约定。 5. 参数解析必须使用项目已有的解析库（如 argparse、commander 或 cobra）。 # 红线 - 禁止引入项目依赖中不存在的第三方库。 - 禁止将业务逻辑写入包入口文件。 - 禁止生成超过 500 行的大文件，超长时拆分为多个模块。 - 必须输出一个使用示例，放在 examples/README.md 中。

然后放两个例子，examples/good_example.md和examples/bad_example.md。坏例子里我专门放了一段“使用自定义参数解析逻辑、把所有命令揉进一个文件、没有任何帮助信息”的代码，并在旁边标注问题；好例子里则是标准的命令行工具结构。这样 Claude Code 看到的是“什么不行 + 什么行”，而不是只有一个努力方向。

写完模板后，我测试了一个真实的 scene：让用它写一个小的todo命令行工具，支持增删改查和--json输出。从结果看，它确实没有再徒手实现参数解析，而是直接沿用了项目里已有的argparse配置方式，文件拆分也符合命令行工具惯例。全程几乎没有需要手工调整的地方。

4.3 模板变量与动态拼接的玩法

如果你只在本地一个人用，模板写死就够了。但如果是团队协作，不同项目对“测试框架”“包管理器”这些变量有不同要求，这时候我推荐做一层轻量拼接。

我没有用复杂的模板引擎，就是用 Python 脚本做字符串替换。核心思路是在模板里留占位符，例如：

测试框架: {{TEST_FRAMEWORK}} 包管理器: {{PACKAGE_MANAGER}}

然后跑一个apply_templates.py，它会去读项目.claude-templates.json配置文件，把对应的变量注入模板目录，最终输出到.claude/templates/让 Claude Code 读取。这种做法成本很低，但解决了每个项目都要 fork 一整套模板的问题。

配置文件的形态大概长这样：

{ "project_name": "user-service", "test_framework": "pytest", "package_manager": "uv", "ignored_dirs": ["migrations", "vendor"] }

4.4 团队级模板的落地方案

最后说下团队使用。我一个人用的时候，模板全在我本地；引入团队后，问题就变成“怎么让所有人都能用到同一套规则”。

我目前的做法是：模板库独立成一个 git repo，通过 git submodule 挂到各业务项目根目录的.claude-templates下。这样更新模板主干时，只需要在业务项目里git submodule update --remote即可。配合一个简单的 pre-commit hook，每次提交前检测模板子模块是否落后于远端，提示开发者及时更新。

团队推广时有一点必须提前约定：每个人可以根据自己的任务场景加新模板，但核心规则（怎么输出、哪些红线）只能通过 PR 修改。否则用不到两周，模板库就会因为个人偏好互相冲突而烂掉。

5. 常见问题与排查技巧实录

5.1 模板不生效 / 输出风格没变化

这是我被问得最多的问题。排查顺序基本是：

第一步，确认模板文件有没有被正确“喂”给模型。Claude Code 不会自动扫描你磁盘上的所有 md 文件，你需要通过@引用或粘贴内容。如果你只是把模板放在templates/目录里但没有在对话中引用，它就和不存在一样。

第二步，检查你的CLAUDE.md是否和模板规则冲突。有过一次，团队同事反馈模板完全不生效，我查了半天发现是项目根目录的CLAUDE.md里写了一句“始终使用函数式组件，不需要遵循项目已有风格”，直接把模板要求顶掉了。记住：模板的优先级未必高于 CLAUDE.md，特别注意多处规则打架的情况。

第三步，看你的任务描述本身够不够清晰。模板约束住了“怎么输出”，但如果你没说清楚“到底要做什么”，模型依然只能猜。你至少要给它明确的输入：改哪个文件、核心诉求是什么、期望产出什么。

5.2 上下文爆炸与成本飙升

启用模板后，单次对话消耗的 token 会明显增加，尤其是引用了examples/的模板，一次多烧几千 token 很正常。我自己的应对方式是控制模板体积，并且不在同一轮对话里同时引用多个模板——只引用和本任务最相关的那个，其他规则靠 CLAUDE.md 兜底。

另外，不要每次对话都重复贴完整模板。Claude Code 有自己的上下文管理机制，但遇到长会话还是会在中段“忘记”早期给出的约束。我的经验是超过 20 轮对话后，如果任务还没完成，果断开新会话，先把模板再次引用一遍，然后一句话总结前面已经查明的信息。省下来的 token 比反复纠正一个“失忆”的模型要多得多。

5.3 中文团队项目里的中英文混杂问题

我们团队的注释和技术文档是中英文混杂的，这给模板带来一个隐藏难题：Claude Code 默认生成的注释和 commit message 是英文，但我们要求注释根据上下文判断使用中文。这个规则直接写进模板后，效果依旧不够稳定。

后来我找到一种更有效的写法：在模板里加入“语言判定规则”：

- 如果被修改文件内已有注释 60% 以上为中文，则新增注释必须使用中文。 - 如果新文件属于业务模块，注释使用中文；属于基础设施/工具类代码，注释使用英文。

这个规则比“根据上下文判断”要具体得多。加进去之后，语言风格的稳定性好了很多。如果你也遇到类似问题，不要只抱怨“它老写成英文”，先想想自己的规则够不够“可判定”。

5.4 模板与现有 CI/CD 的协作问题

还有一种常见情况是：模板生成的代码本地跑得好好的，推到 CI 上就挂。原因多半是模板里没有约束“必须检查 CI 配置”。比如项目 CI 用的是pytest-cov带 80% 覆盖率阈值，模型生成的测试用例数量不够直接把覆盖率拉低，导致流水线失败。

解决办法是在模板红线里显式加两条：

• 生成或修改代码后，必须运行 CI 脚本中对应的检查命令；
• 如果项目存在覆盖率阈值，新增逻辑必须有对应测试用例支撑。

5.5 一张排查速查表

最后把这些经验汇总成表，方便你遇到问题时快速定位：

最后说几句实在话

从个人玩票到团队正式落地，这缝合怪一样的模板库前前后后折腾了好几周。最大的体会是：模板这件事，收益最大的是“中期会话”，也就是任务复杂度介于“一个函数”和“一次架构升级”之间的场景。太小的任务用不上模板，太大的任务模板也撑不住，后面还得靠人自己拆解。

如果你打算一开始就复刻一套，别贪多。先从两个场景开始：unit-test和commit-message，一个解决你的“事后检查负担”，一个解决 AI 生成的提交信息不一定符合团队规范的问题。跑顺了，再把你真正高频的场景逐步加进去。别一上来就把十个模板全配上，规则之间互相打架的那几天，真的很让人崩溃。