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 读取项目说明的天然入口，而且会对每个会话自动生效。很多人喜欢把它写成项目说明书，架构图、需求背景、功能清单全往里面塞。我的经验是：塞得越多，模型反而越容易把无关信息当成约束条件来遵守。基础层只需要放三样东西。
第一样是项目的基本盘。语言、框架、目录结构、启动命令、测试命令。给它一张最小地图就够了。比如写清楚“前端在 /web，Vite + React；服务端在 /api，FastAPI；测试统一用 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 协作的偏好从个人大脑里搬进了项目资产里。偏好只存在于你脑子里的时候，换一个人、换一个会话就归零了。一旦落成目录、落成文件、落成团队的评审习惯，它的收益就开始累积了。每一次修模板，都是在减少下一次会话的不确定性。做工具的核心价值不在于工具本身有多精致，在于它能让后面的事情持续变得更顺。
