1. 为什么要给 Claude Code 建一套模板库而不是每次重新“从零教学”先说一个场景。你手里有三个项目同时在维护语言不同测试框架不同注释习惯不同。打开 Claude Code 之前你得先在脑子里把“这个项目的地图”重新装一遍目录结构什么样、测试命令是什么、代码风格有哪些约束、哪些目录是碰不得的。然后你开始敲需求敲完等它输出再发现它连项目用的什么构建工具都没搞清楚。这时候你多半会补一句“先去看一眼 README 和 pyproject”。对话次数多了你会发现这种“从零唤醒”的损耗根本不是偶发它是日常。每一次新会话模型对项目的认知都归零而你把同样的背景信息重新输一遍、再让它去读一遍文件这个过程极其稳定地浪费时间和心智。更烦的是输出结果不稳定同一个“帮我 review 这次改动”的需求今天它给你一份分点清晰的结论明天它可能就开始帮你写一段“整体风格良好”的废话。不是模型变笨了而是你每次给它的上下文质量波动太大。我建立这套 claude-code-templates 的初衷就两条第一把每个项目的基础约定沉淀成一个稳定层不用每次重新教第二把高频任务的完成标准和输出格式固定成一份可以直接调用的“任务说明书”。说白了这就是封装。你写代码的时候不会在每个文件里重新实现一遍排序逻辑那你也没理由让每个新会话都从零学习你的偏好。还有一层原因是团队协作逼出来的。团队里不同人写的 review prompt 五花八门同一次 commit两个人审查的标准完全不同一个抓安全不抓风格另一个反着来。这个时候你没法靠口头约定了你得把“我们的审查到底要输出什么、按什么优先级判断”写成一个团队统一认可的东西。不然所谓的协作规范最后一定是各写各的 prompt各按各的标准做事。这篇我会给出一套我实测过的组织方式分基础层和任务层两层来管理。也会把我踩过的坑原原本本讲一遍包括版本过期的模板怎么坑了我的 CI、模板规则和 CLAUDE.md 冲突时模型会怎么“两头讨好”然后翻车。不说废话直接上干货。2. 模板虽叫 templates但我不建议只堆 prompt 目录如果你把 claude-code-templates 理解成“一个装满一堆提示词文本的文件夹”那它跟浏览器收藏夹没有本质区别顶多整理了一点。真正的价值在于把模板拆成两层一层管项目的基本盘另一层管具体任务怎么干。这样模板才不是一堆孤立文本而是一套可复用的协作基础设施。2.1 基础层CLAUDE.md 只放三样东西第一层是基础层载体是 CLAUDE.md。它是 Claude Code 读取项目说明的天然入口而且会对每个会话自动生效。很多人喜欢把它写成项目说明书架构图、需求背景、功能清单全往里面塞。我的经验是塞得越多模型反而越容易把无关信息当成约束条件来遵守。基础层只需要放三样东西。第一样是项目的基本盘。语言、框架、目录结构、启动命令、测试命令。给它一张最小地图就够了。比如写清楚“前端在 /webVite React服务端在 /apiFastAPI测试统一用 pytest跑pytest tests/”模型就有能力自己去探索细节不需要你事无巨细地描述每个模块。第二样是协作规则注释用中文还是英文commit message 的格式review 时最在意什么。这些属于“和人协作时的规矩”模型不知道就会自由发挥而自由发挥在团队项目里往往是灾难。第三样是禁区哪些目录不要动、生成的代码不要自动格式化整个文件、涉及数据库结构变更时只给 SQL 不要直接执行。把这些写清楚能省掉很多“纠正模型错误行为”的来回拉扯。还要注意别放什么东西。具体某次任务的执行细节不要放经常变动的信息比如依赖版本不要放。基础层是每次会话都要加载的内容必须少而稳定不是拿来记流水账的地方。我见过有人把“本项目所有 API 返回结构”写进 CLAUDE.md结果模型随便生成一份接口代码就开始照虎画猫。这类信息该进项目文档的时候进文档别压给基础层。2.2 任务层一个模板文件的前置声明、正文与变量设计第二层是任务层存放按任务类型拆分的完整提示词。我的目录结构大致是这样的claude-code-templates/ ├── CLAUDE.md ├── templates/ │ ├── review/ │ │ ├── code-review.md │ │ └── security-review.md │ ├── testing/ │ │ ├── unit-test.md │ │ └── integration-test.md │ ├── refactor/ │ │ └── safe-refactor.md │ └── docs/ │ └── changelog.md └── scripts/ └── apply.sh每个模板文件开头固定放一段“前置声明”写清楚这个模板在什么场景下用、需要替换哪些占位符、它默认遵循什么样的规则。正文里用[变量]标注需要填写的位置方便直接粘贴也方便将来用脚本做参数替换。比如代码审查模板里你可以写“需要审查的 commit 范围[commit-sha1]..[commit-sha2]”到了用的时候把真实值填进去就行。怎么把模板喂给 Claude我试过两条路线。交互式会话里直接读模板文件内容适合低频任务写一个很薄的包装脚本在命令行里把模板和当前任务的上下文拼装好再调用适合高频重复的任务。做到脚本层之后模板就不再是“每次都要复制粘贴的一段话”而是真的有了一点工程基建的味道。我为什么坚持分两层这个问题的答案很实际。CLAUDE.md 是每次会话自动加载的它必须短、稳、对全局有用任务模板是具体任务才加载的它可以长、苛刻、只服务于一个目标。两者一旦混在一起要么基础层臃肿要么任务层缺少项目背景的支撑。分开之后基础层提供稳定底色任务层在需要时精准注入上下文成本和输出质量都能兼顾。3. 我实际在用的三个模板review、单测、重构下面这三份模板都是我在项目里跑过很多轮的版本。我会把模板贴出来同时把每一步为什么要这样设计讲清楚。你拿去用可以但我更希望你能理解背后的判断逻辑然后改出你自己的版本。3.1 代码评审模板风险分级比审查结论更值钱早期我的代码审查提示词相当朴素大概就是“你看看这段代码有什么问题”。用它跑出来的结果很不可用模型先来一句“整体代码良好”然后罗列一堆万金油建议。真正做 review 的人需要知道的是“哪里有问题、有多严重、应该怎么改”而且这三件事的顺序不能乱。我后来迭代成这样你是一名资深代码评审工程师。请审查我提供的代码变更。 审查优先级 1. 功能性错误、逻辑漏洞、明显的边界遗漏 2. 安全风险注入、越权、信息泄露、不安全的反序列化 3. 性能问题不必要的循环、重复计算、可避免的 IO 4. 可维护性命名、函数长度、重复代码、魔法数字 输出格式 - 风险等级每个问题标注 [严重] / [一般] / [建议] - 问题位置精确到文件和函数 - 修改建议给出可直接执行的方案不要只说“建议优化” - 最终结论是否建议合并如果有必要列出必须修复的问题编号 约束 - 不要逐行赞美不要输出“整体不错”类的套话 - 不要引入项目里不存在的架构偏好 - 如不确定某项行为是否符合业务预期标注“需与需求方确认”不要自行假设这个模板值得说的设计点有三个。第一风险等级前置。把输出变成一条可排序、可追踪的清单而不是一篇没法消费的散文。Code Review 是要被讨论和跟进的清单形态天然适合。第二“不要输出套话”这条约束看着像在骂模型但它真的能把输出压缩到只有有效信息。第三“不要假设业务行为”这条是最容易被忽略的。AI 审代码的时候经常会混淆“代码是否整洁”和“代码是否符合业务预期”它其实不具备后者的判断能力很容易把一个写法上不漂亮但业务上有意为之的实现标成问题。有了这条约束它至少会停下来标注一个“需与需求方确认”而不是自作主张。还有一个实际经验小改动直接把 diff 贴在模板后面输出质量最稳大改动让模型结合提交历史和 diff 来看效果更好但你要保证它读取的代码是在正确分支和正确状态下的。这属于使用细节但直接影响审查结果值得留意。3.2 单元测试模板从“生成用例”改为“防回归清单”写单元测试是我用 Claude Code 最频繁的场景之一也是最容易生成“看起来对、实际没测到点上”的场景。问题出在目标描述上。如果你只说“为这个函数生成单元测试”它通常会生成一堆 happy path 用例断言写得很满但边界条件和异常分支一个没碰。测试的真正价值在于覆盖你没想过的情况而不在于凑覆盖率的数字。我的测试生成模板加了这些硬约束你是一名资深测试工程师。请针对以下代码生成单元测试。 要求 1. 覆盖范围必须包含正常路径、边界值空、零、超长、负值、异常输入和主要分支 2. 为每个测试用例写一行说明解释它在防什么回归 3. 测试代码的注释语言与项目一致 4. 不要改动被测代码只新增测试文件 5. 使用项目现有的测试框架和断言风格不要引入新依赖 6. 若被测函数本身有设计问题在文件末尾用“设计隐患”小节列出不要中断生成第六点是踩坑后的重要补充。早期模板没有这条模型遇到有问题的源码时会突然停下来因为它把“发现 bug”和“生成测试”两件事搅在了一起。加上这条之后它会先把能测的测完把设计上的疑虑统一汇总产出的质量稳定很多。另外第二点很容易被忽略但我觉得它才是测试模板的精华。让模型为每个用例解释“在防什么”它就会被迫去思考这个用例存在的理由而不是机械地写三行断言。3.3 行为保持重构模板先列输入输出样例再动代码重构大概是 AI 编程里最难做稳的任务之一。“保持行为不变”是原则但模型在优化的过程中特别容易顺手改掉不该改的细节。它会把一个校验顺序换掉或者把返回值从None改成空列表表面看起来更“合理”调用方的行为却完全变了。我用的重构模板长这样你是一名资深重构工程师。目标在保持外部行为不变的前提下优化代码结构和可维护性。 硬性约束 1. 不允许改变函数签名、返回值语义、异常类型和对外可观察的行为 2. 重构前先列出输入输出样例重构后用你给出的样例自我验证 3. 重构后必须说明改了什么、为什么改、可能影响到的调用方 4. 如果某次修改无法保证行为一致必须单独标注不要强行合并 5. 不要顺手格式化代码不要顺手改注释除非注释本身已错误 6. 涉及性能优化时必须提供基准对比结论不要只说“更快了”第一条和第四条是这个模板的灵魂。第一条约束了改动边界第四条约定了不确定性时的处理方式。这两条加在一起模型就没办法在“不确定”的时候凭感觉继续。第二条“先列输入输出样例并自我验证”是给它建一个最小测试闭环。这当然替代不了真正的测试套件但能在生成阶段就拦住大量低级回归。提一下第五条的背景。很多项目有自己独立的格式化流程模型认为的“漂亮格式”在团队里反而可能是噪音而且 review 时还分不清哪些是真实改动。所以我特意加了“不要顺手格式化”这条。它带来的副作用是重构后的代码可能“风格不一致”但那个问题交给项目的格式化工具统一处理就够了不该由 AI 的好恶决定。4. 模板翻车实录版本过期、上下文污染、规则打架模板用多了翻车是必然的。我把自己踩过的坑整理成三条每一条都对应一套修整对策。看完你就知道模板写出来只是一个开始维护它才是真正的挑战。第一坑是版本过期。我有一份后端模板里面写了“图片处理库使用 Pillow”因为项目确实一直在用。过了一段时间模型生成的代码里引用了 Pillow 已经弃用的接口CI 直接报错。问题根源不是模型而是模板里的技术信息没有校准。修整方案很简单把模板里所有涉及技术栈和版本的位置改成“去项目里现查”的描述。不写“用 Pillow 10.x”而是写“图片处理库以项目依赖文件中的声明为准优先使用当前主流 API”。你会觉得这种写法更含糊但它能有效避免模板老化。另外给模板加一个更新日期字段按季度整体过一遍是个成本低、收益稳的习惯。第二坑是上下文污染。有一段时间我恨不得把模板写得越长越好感觉信息量越大模型越懂。结果恰恰相反。一次我在 Python 项目的测试模板里同时写了风格要求、版本要求、依赖清单、注释语言要求以及一条“不要用 mock 库要用 unittest.mock”的历史嘱咐。着看关键词。它生成的代码里 import 出现了项目根本没在用的库还平白加了一个多余的 fixture。它不是在欺骗我而是把模板里的参考信息当成了必须实现的条件过度拟合了。修整方案是给模板内容分级。必备规则用“必须”“不允许”这种强语义词参考信息用“可以”“视情况”这种弱语义词。强规则数量严格控制最多五条弱规则可以多一些但必须和任务强相关。模板是约束条件不是百科全书。第三坑是规则打架。这里最隐蔽也最伤。举一个实际例子CLAUDE.md 里写了“项目注释统一使用英文”但有人拿一份按中文注释写的模板跑别的项目忘了改。模型没直接报错它在注释输出时纠结了最后生成的文件一半中文一半英文反而增加了一轮 review 工作量。还有一次CLAUDE.md 说“不要自动格式化代码”模板却写了“重构时整理代码格式”两边冲突模型选择了妥协最终 diff 里混入大量无关的格式调整。我的对策是两件事。第一模板文件头部强制放一段前置声明把默认规则写清楚让人在粘贴前意识到它可能和当前项目的基础规则冲突。第二模板里加一条冲突处理指令以 CLAUDE.md 的规则为优先级有冲突先暂停并列出冲突点。这样即使两边打架模型也不会闷头按模板执行而会先把矛盾暴露给人处理。踩过这些坑我重新理解了模板的定位它是“每次重新教育模型的缩减版”不是“让模型自动完美的配方”。模板能不能用不取决于写得多漂亮而取决于你能不能在它出错时快速定位是模板的问题还是使用的问题。5. 把模板当产品维护版本管理、灰度替换和新人上手模板一旦进入多人协作的场景就变成一个小型产品要管版本、定流程、看使用反馈。我把模板仓库用 Git 管理起来但重点其实不在 Git 本身而在几套配套习惯。第一套习惯是变更走流程。任何模板的修改都走 pull request哪怕只改了一个词。理由很简单模板会影响所有使用它的会话的输出质量一次草率的改动会在十几个分支里被放大。PR 里附带一个实测样例用改后的模板跑一次真实任务把输出摘要贴上去。这样 reviewer 能快速判断改动方向而不是凭感觉猜。第二套习惯是灰度替换。从部署工程里借来的思路。一个模板准备替换旧版本时不直接全量更新。先在个人分支或一个小项目上跑两轮确认输出质量不低于旧版再合入主分支。如果项目比较复杂挑一两个场景做对比同一段代码旧模板和新模板各跑一次比较输出结构完整性和可用性。这个过程通常不到十分钟但能避免“过了一个星期才有人说这模板不如原来好用”的尴尬回滚。第三套习惯是给新人留一扇门。模板文件夹不能只有一堆 md得有一个 README用最直白的话写清这些模板是干什么的、什么时候该用哪份、怎么喂给 Claude。同时README 里必须写一句“模板是辅助不是教条。如果任务有特殊要求优先满足任务而不是硬套模板。”这句话既防止团队为了用模板而用模板也能触发大家对模板本身的修正动力。关于自动化我最后补一句。当模板和命令行用法固定下来之后下一步很自然就是把它嵌进 git alias、CI 流程之类的地方。但我的建议是别为了自动化而自动化。模板的 80% 使用场景还没跑顺之前先把手工流程用透、把输出质量稳住比急着接一条流水线更重要。等团队习惯了模板的产出质量再逐步自动化才不会自动化了一套没人爱用的流程。回头看我维护这套 claude-code-templates 的最大心得它真正改变的不是“我写了一段好用的提示词”而是让我把跟 AI 协作的偏好从个人大脑里搬进了项目资产里。偏好只存在于你脑子里的时候换一个人、换一个会话就归零了。一旦落成目录、落成文件、落成团队的评审习惯它的收益就开始累积了。每一次修模板都是在减少下一次会话的不确定性。做工具的核心价值不在于工具本身有多精致在于它能让后面的事情持续变得更顺。