前几天把一套自己一直在用的提示词模板整理成了开源项目姑且就叫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-componentReact 组件开发约束点是组件拆分粒度、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 一个合格模板的七条标准经验总结我把踩坑踩出来的经验浓缩成七条你写模板时可以直接拿来自检模板必须给出反面示例只给正面示例模型会倾向于模仿句式而不是理解约束每条规则都要能“被验证”比如“不添加依赖”就比“尽量少加依赖”有效得多模板长度控制在 150-300 行之间太短约束不够太长模型注意力会被稀释场景分类宁多勿少一个“通用模板”远不如 6 个场景模板加起来好用格式用列表和短句模型对列表格式的遵循度远高于长段落规则之间不能互相矛盾比如既让它“保持最小改动”又让它“顺手优化相关模块”模型会陷入混乱每次跑完重要任务后顺手把失败的输出反馈回模板让它在实例里多一个反面教材。3.3 默认输出与模板化输出的差异对比下面这张表来自我最近把模板推到团队后的一次实测对比。同一个仓库、同一个任务给一个用户服务模块补单元测试模板开与不开差异明显对比维度未启用模板启用单元测试模板测试框架随机选了一个新依赖与项目不符遵循项目已有的 pytest 风格用例覆盖点只覆盖正常流程补充了异常分支、边界值、依赖失败场景是否改动源码顺带改了 3 个函数的返回逻辑源码零改动新增依赖2 个0 个用例命名风格随意与现有测试命名保持连续耗时含手工修正40 分钟15 分钟表格最后一行其实是最关键的价值指标。模板化不会让你完全不用看 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 一张排查速查表最后把这些经验汇总成表方便你遇到问题时快速定位现象原因解决方案模板完全不生效模板未被引用确认已通过引用或粘贴完整模板到对话模板部分规则没生效与 CLAUDE.md 或全局规则冲突检查所有规则源整理优先级输出格式偏离模板范例范例太少或太模糊增加 2-3 个正反示例细化规范多轮对话后期质量下降上下文过长模型遗忘早期约束重开会话重新引用模板与工作摘要中英文注释混杂模板没有明确的语言判定机制定义可按文件统计判定语言的具体规则生成的代码无法通过 CI模板未覆盖 CI 检查命令与覆盖率门槛在红线中显式加入 CI 命令和覆盖率约束团队内模板越改越乱没有统一的修改入口独立仓库 PR 审核核心规则变更最后说几句实在话从个人玩票到团队正式落地这缝合怪一样的模板库前前后后折腾了好几周。最大的体会是模板这件事收益最大的是“中期会话”也就是任务复杂度介于“一个函数”和“一次架构升级”之间的场景。太小的任务用不上模板太大的任务模板也撑不住后面还得靠人自己拆解。如果你打算一开始就复刻一套别贪多。先从两个场景开始unit-test和commit-message一个解决你的“事后检查负担”一个解决 AI 生成的提交信息不一定符合团队规范的问题。跑顺了再把你真正高频的场景逐步加进去。别一上来就把十个模板全配上规则之间互相打架的那几天真的很让人崩溃。 
长河君 · 2026/10/17 17:09:19 · 阅读 1.2k Claude Code提示词模板实战：让AI编程助手更稳定可控
前几天把一套自己一直在用的提示词模板整理成了开源项目姑且就叫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-componentReact 组件开发约束点是组件拆分粒度、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 一个合格模板的七条标准经验总结我把踩坑踩出来的经验浓缩成七条你写模板时可以直接拿来自检模板必须给出反面示例只给正面示例模型会倾向于模仿句式而不是理解约束每条规则都要能“被验证”比如“不添加依赖”就比“尽量少加依赖”有效得多模板长度控制在 150-300 行之间太短约束不够太长模型注意力会被稀释场景分类宁多勿少一个“通用模板”远不如 6 个场景模板加起来好用格式用列表和短句模型对列表格式的遵循度远高于长段落规则之间不能互相矛盾比如既让它“保持最小改动”又让它“顺手优化相关模块”模型会陷入混乱每次跑完重要任务后顺手把失败的输出反馈回模板让它在实例里多一个反面教材。3.3 默认输出与模板化输出的差异对比下面这张表来自我最近把模板推到团队后的一次实测对比。同一个仓库、同一个任务给一个用户服务模块补单元测试模板开与不开差异明显对比维度未启用模板启用单元测试模板测试框架随机选了一个新依赖与项目不符遵循项目已有的 pytest 风格用例覆盖点只覆盖正常流程补充了异常分支、边界值、依赖失败场景是否改动源码顺带改了 3 个函数的返回逻辑源码零改动新增依赖2 个0 个用例命名风格随意与现有测试命名保持连续耗时含手工修正40 分钟15 分钟表格最后一行其实是最关键的价值指标。模板化不会让你完全不用看 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 一张排查速查表最后把这些经验汇总成表方便你遇到问题时快速定位现象原因解决方案模板完全不生效模板未被引用确认已通过引用或粘贴完整模板到对话模板部分规则没生效与 CLAUDE.md 或全局规则冲突检查所有规则源整理优先级输出格式偏离模板范例范例太少或太模糊增加 2-3 个正反示例细化规范多轮对话后期质量下降上下文过长模型遗忘早期约束重开会话重新引用模板与工作摘要中英文注释混杂模板没有明确的语言判定机制定义可按文件统计判定语言的具体规则生成的代码无法通过 CI模板未覆盖 CI 检查命令与覆盖率门槛在红线中显式加入 CI 命令和覆盖率约束团队内模板越改越乱没有统一的修改入口独立仓库 PR 审核核心规则变更最后说几句实在话从个人玩票到团队正式落地这缝合怪一样的模板库前前后后折腾了好几周。最大的体会是模板这件事收益最大的是“中期会话”也就是任务复杂度介于“一个函数”和“一次架构升级”之间的场景。太小的任务用不上模板太大的任务模板也撑不住后面还得靠人自己拆解。如果你打算一开始就复刻一套别贪多。先从两个场景开始unit-test和commit-message一个解决你的“事后检查负担”一个解决 AI 生成的提交信息不一定符合团队规范的问题。跑顺了再把你真正高频的场景逐步加进去。别一上来就把十个模板全配上规则之间互相打架的那几天真的很让人崩溃。