1. 模板不是约束，是让 Claude Code 从"聪明"变"靠谱"的杠杆
先说一个我自己的真实感受。最早用 Claude Code 的时候，我的体验可以用四个字形容：飘忽不定。同一个任务，如果我把需求描述得足够清楚，它能给出接近完美的方案；但如果我偷懒只说一句"帮我把这个接口改一下"，它也能交差，但交出来的代码风格明显不是这个项目该有的样子——命名习惯不对、错误处理缺失、注释风格也不同。当时我一度以为是模型的问题，后来才意识到：问题不在模型，在我没有给它一套稳定的"游戏规则"。
这个"规则"就是模板。
所谓 claude-code-templates，通俗讲就是为 Claude Code 准备的一套可复用的提示词模板、项目级指令文件和命令注册机制。它解决的不是"能不能用"的问题，而是"好不好用""稳不稳定"的问题。举一个类比：同样一位厨师，给他一份清晰的菜谱和标准化的食材清单，他做出来的每道菜都能保持水准；如果每次只口头说"做道好吃的"，那结果全看当天心情。Claude Code 其实也一样，模板就是那份菜谱。
我一直觉得，很多开发者对 Claude Code 的使用还停留在"聊天式编程"的阶段：打开终端，输入一句话，等结果。这种用法不能说错，但它完全浪费了 Claude Code 最核心的能力——可编程性。你可以通过模板、配置文件、命令系统，把它从一个被动应答的工具，变成一个能主动遵循项目规范、理解团队约定、甚至能自动执行固定流程的"编码伙伴"。
这篇博文就把我自己搭建的 claude-code-templates 完整分享出来，包括设计思路、分层结构、具体模板内容、安装方式，以及迭代过程中踩过的坑。如果你正在用 Claude Code，但觉得回答质量不稳定、风格不统一、每次都要反复说同一堆要求，这篇文章应该能帮到你。
2. 先搞清楚三个层级的模板体系：CLAUDE.md、CLAUDE.local.md 与斜杠命令
很多人以为模板就是一堆提示词字符串，其实不是。我自己的模板体系是三层结构，每一层解决不同粒度的问题。理解这三层，你才能理解为什么有些模板"放对位置"能发挥巨大作用，放错位置却毫无效果。
2.1 第一层：CLAUDE.md——全局记忆与项目契约
CLAUDE.md 是 Claude Code 在项目根目录下自动读取的指令文件，类似给整个会话注入的"项目背景知识"。每次启动会话，它都会把这个文件内容作为上下文的一部分，所以这里面应该放的是所有任务都适用的、稳定不变的规范。
我当时设计 CLAUDE.md 时，里面放了四块内容：
- 项目一句话定位：这个仓库是干什么的、主要技术栈是什么、目标用户是谁；
- 代码风格约束：命名规范、目录组织、注释风格、错误处理要求；
- 架构边界：哪些模块不允许互相依赖、数据流向是什么、核心不可变原则有哪些；
- 安全与质量红线：比如不允许把密钥写进代码、不允许跳过测试、生产代码必须加日志等。
一开始我把 CLAUDE.md 写得非常长，恨不得把团队的编码规范书全塞进去。后来发现不行，因为上下文空间有限，而且太长的规则 AI 根本"抓不住重点"，反而影响其他指令的执行。最终我精简到了不到 60 行，只保留那些最容易违反、且违反后代价高昂的规则。
举个例子，我们项目里有一条"禁止在 API 层直接透传数据库异常"的约定。这条如果不写在 CLAUDE.md 里，Claude 经常会在生成的代码里写catch (Exception e) { throw e; }，责任链完全断掉。写进去之后，类似的问题几乎绝迹。
2.2 第二层：CLAUDE.local.md——个人偏好与实验场
CLAUDE.local.md 和 CLAUDE.md 的机制类似，但它更适合放只对自己生效、不需要提交到版本库的内容。按我的理解，它的定位是"本地实验场"和"个人快捷键"。
我自己会在 CLAUDE.local.md 里放什么？比如：我最习惯的回复风格（"先给结论再给细节"）、我在这个项目里经常使用但团队其他人不用的命令别名、我个人的目录偏好等。这些内容如果放进 CLAUDE.md 提交给团队，可能会干扰其他人的使用习惯，但放在 local 文件里就恰到好处。
还有一点很关键：CLAUDE.local.md 默认应该加入 .gitignore。因为它本来就是个人偏好，提交到仓库里属于污染共享配置。
2.3 第三层：斜杠命令模板——把高频动作固化为标准流程
这是整套模板体系里最能提升效率的部分，也是最容易被忽略的。Claude Code 支持斜杠命令（slash commands），实现方式是：在项目的.claude/commands/目录下放一批 markdown 文件，文件名就是命令名。比如建立一个review.md，里面写好"以资深代码审查者的身份，对指定文件进行逐项审查"的提示词，之后你在终端里输入/review src/foo.ts，它就会自动按模板执行。
我的 claude-code-templates 项目里，核心资产其实就是这些命令文件。它们把"高频、重复、且有标准动作"的任务固化成了可一键调用的流程。我想强调的是，斜杠命令和普通提示词最大的区别是：命令本身可以自带逻辑结构。
比如一个测试生成命令，它不只是简单写一句"帮我写测试"，而是在模板里规定了：先分析被测函数的行为边界，再列出需要覆盖的分支，接着按团队的测试命名规范生成用例，最后检查断言完整性并补一个边界条件测试。这样每次调用，产出的不是"一段能跑的测试代码"，而是"符合团队标准、覆盖完整的测试集"。
2.4 三层的协作关系：一个完整需求是怎么流转的
这三层的分工可以这样看：CLAUDE.md 管"项目人设和底线"，是会话启动时的背景知识；CLAUDE.local.md 管"个人适配层"，是个性化补充；斜杠命令管"单次动作的执行路径"，是遇到具体任务时的操作手册。
举个例子，我让 Claude Code 给一个 API 写单元测试。它会这样运转：首先加载 CLAUDE.md，知道项目用的是 Jest、测试文件放在__tests__目录、命名格式是*.test.ts；然后我调用/test斜杠命令，它读取命令模板，明白当前任务是"对 utils 模块的 dateFormat 函数补测试"；执行过程中如果遇到风格上的小问题，比如我偏好用describe的嵌套层级而不是扁平结构，CLAUDE.local.md 里的个人配置会自动修正。
这里最核心的心得是：模板不是替代你的思考，而是把你的思考固化成可重复执行的流程。你只需要花一次时间把流程想清楚，之后每一次调用都在复利。
3. 我实际在用的五类模板：从测试生成到架构评审的完整拆解
前两节讲的是框架和原理，这一节给你看具体的模板内容。我把自己的模板仓库按场景分成了五类，每一类都有明确的适用范围和效果预期。你可以直接抄走，再根据自己的情况调整。
3.1 测试生成模板：让 AI 先列分支再写用例
最早让我下定决心做模板的，就是测试生成。因为 Claude Code 写 "happy path"（正常路径）的测试几乎从不失手，但边界条件和异常分支经常漏掉。与其每次补充提醒，不如把要求直接固化进模板。
这个模板的关键不是最后那段"请生成测试"的指令，而是它强制 AI 先完成一个前置动作：列分支清单。
模板的核心内容如下（.claude/commands/test.md）：
你是一名对质量有执念的测试工程师。针对用户给定的文件或函数，按照以下流程生成单元测试： 1. 先阅读被测代码，列出所有需要覆盖的行为分支，包括： - 正常输入路径 - 空值 / 未定义 / 类型异常 - 边界值（如 0、负数、超长字符串、最大整数） - 依赖函数抛错时的传播行为 - 对全局状态 / 定时器 / mock 的预期交互 2. 将分支清单展示出来，等待用户确认。如果用户没有特别补充，直接执行下一步。 3. 按团队成员熟悉的测试风格编写用例：使用 Jest 框架，文件命名 {name}.test.ts，describe 嵌套按模块/函数/场景三层组织。每个测试用例必须以中文注释描述行为意图。 4. 断言必须包含"正确结果"和"副作用检查"两个维度。例如测试一个缓存函数，不仅要断言返回值正确，还要断言缓存被写入、写入次数为 1。 5. 所有外部依赖必须显式 mock，禁止依赖真实网络请求或时间函数。在使用这个模板之前，Claude Code 生成的测试大概能覆盖 60% 的分支；用了之后基本稳定在 90% 以上。剩余那 10% 往往是被测代码本身的写法有问题，不是模板的问题。
3.2 重构模板：先出方案，确认后再动手
重构类任务最容易出事故的地方是：AI 太勤快，你说"帮我优化一下这段代码"，它直接把整个函数翻了个底朝天，行为完全变了，你还得手动 review。这非常危险。
所以我的重构模板（.claude/commands/refactor.md）铁律只有一条：不许先改代码，先写方案。模板在其中强制规定了方案必须包含哪些要素：
你是资深软件架构师。收到重构请求后，严格按下列步骤执行： 1. 阅读目标代码及其调用方，识别真实职责和隐式耦合。 2. 输出重构方案，必须包含以下七个部分： - 现状问题清单（按严重程度排序） - 重构目标（明确哪些行为不允许改变） - 方案设计（包含代码级别的变更要点） - 影响范围分析（列出所有受影响调用点） - 风险提示（哪些行为可能因重构而变化） - 验证策略（如何确认重构不破坏原有行为） - 回滚预案（如果出问题，如何快速恢复） 3. 输出方案后立即停止，等待用户明确说"开始执行"。 4. 执行时必须分步提交，每完成一步就展示变更和对应测试结果，禁止一次改完整个文件再汇报。这个模板的价值在于：把"AI 单方面行动"变成了"人类决策 + AI 执行"的协作模式。重构这种高风险操作，决策权必须留在人手里。
我印象很深的一次：用它重构一个老模块时，AI 在影响范围分析里点出了一个我完全没想到的调用链——有个远程配置文件会通过反射方式调用这个模块里的类名，重构后类名变了会导致线上配置失效。这个风险如果没有提前暴露，后果很严重。
3.3 调试模板：用"现场信息"代替 AI 瞎猜
调试是另一种需要纪律的场景。Claude Code 在没有足够信息时，会倾向于"猜测 + 建议"而不是"排查 + 定位"。过去的对话里，它经常给我提出十几个可能原因，每个看起来都对，但就是没一个能直接解决问题。
调试模板（.claude/commands/debug.md）的思路是：先收集信息，再给出假设，后验证假设。模板会强制 AI 按这个顺序行动：
你是一名严谨的 Debug 专家。用户会提供一个 Bug 现象描述。你的任务顺序是： 1. 信息收集阶段（不允许越级）： - 请用户提供完整错误堆栈、相关代码片段、输入输出样例、环境版本信息。 - 如果信息不足，列出"需要但缺失的信息清单"并明确询问，禁止直接开始猜测。 2. 假设生成阶段： - 基于已有信息列出 2-3 个最可能的根因假设，每个假设给出置信度。 - 为每个假设设计一个最廉价的验证实验，优先选择日志输出或最小复现代码。 3. 验证执行阶段： - 按置信度从高到低逐一验证；每验证完一个假设，必须记录结果并更新剩余假设的置信度。 4. 根因确认后，提供修复方案，并在修复后补充一条回归测试用例。这个模板的效果非常显著——它把 AI 的"发散性建议"强制收敛成了"结构化排查"。用了一段时间之后，我的真实感受是：Claude Code 在"有纪律的思考"模式下，准确率比自由发挥模式高一大截。因为它本身就有很强的推理能力，只是平日里缺少一个约束它按正确流程思考的框架。模板本质上就是在做这件事。
3.4 代码审查模板：让 AI 扮演"最难搞的同事"
代码审查是模板收益最直接、最容易量化的场景。我写的审查模板（.claude/commands/review.md）会系统检查提交代码的多个维度，并以表格形式输出结果。模板的核心是定义了审查的维度清单：
你是代码审查专家。审查用户提供的代码或变更，按以下维度逐项评估，并以表格输出（列：维度 / 评分 / 问题描述 / 建议）： 1. 正确性：是否存在逻辑错误、并发问题、边界遗漏。 2. 安全：是否有注入、敏感信息泄露、权限缺失、不安全的反序列化。 3. 性能：是否有明显性能瓶颈、N+1 查询、不必要的重复计算。 4. 可维护性：命名是否表意、函数是否过长、职责是否单一。 5. 测试覆盖：关键分支是否缺失测试，测试断言是否有效。 6. 风格一致性：是否符合项目已有的编码约定（对照 CLAUDE.md 中的规则）。 7. 潜在技术债：是否存在可以简化但暂时没简化的写法，给出理由。 最终输出必须包含一段总结：如果评分低于 7 分，明确给出"必须修改才能合并"的条目；7 分以上，也要给出至少一个改进建议。这个模板我用得最多，因为它是纯"只读"操作，不会改坏代码，所以可以放心大胆地在任何规模的项目上跑。对大型 PR 而言，它能快速覆盖一些人工容易漏掉的维度，虽然不能替代人的判断，但作为第一道过滤器非常趁手。
3.5 提交信息与变更记录模板：收尾工作的自动化
很多人忽略提交信息也是一项值得模板化的任务。Claude Code 能通过git diff了解变更内容，但默认生成的提交信息经常过于笼统，不符合 Conventional Commits（约定式提交）规范。
提交信息模板（.claude/commands/commit.md）做三件事：读取 diff、归类变更类型、按规范生成提交信息。同时在最后会附上一份"变更摘要"，方便直接用于 PR 描述。
请根据 git diff（如果没有提供，自动执行 git diff --stat 和 git diff）生成符合 Conventional Commits 规范的提交信息。 要求： - type 根据变更内容选择：feat / fix / refactor / docs / test / chore / perf。 - 正文必须包含三个部分：变更动机、具体变更内容、影响说明。 - 如果包含破坏性变更（BREAKING CHANGE），必须在 footer 中标注，并说明迁移路径。 - 生成的提交信息控制在 10 行以内（header + 正文 + footer），每行不超过 72 字符。 - 变更摘要部分用自然语言概括本次 PR 的影响范围，适合直接粘贴到 PR 描述。这类模板对个人项目可能用处不大，但如果你在团队里工作，提交信息的规范性能省下不少"被同事点名修改 commit message"的尴尬。
4. 模板仓库的工程化落地：从手写文件到标准化管理的完整流程
有了模板内容之后，还有一个工程问题：如何管理这些模板文件、如何确保它们在不同项目之间复用、如何迭代升级。这一节把我的落地方式完整拆开讲。
4.1 模板仓库的目录结构设计
我的 claude-code-templates 仓库采用了如下结构：
claude-code-templates/ ├── README.md # 使用说明：如何安装、如何自定义 ├── commands/ # 斜杠命令模板 │ ├── test.md │ ├── refactor.md │ ├── debug.md │ ├── review.md │ └── commit.md ├── CLAUDE.md # 项目级通用指令模板 └── CLAUDE.local.md.example # 个人配置的示例文件实际操作中，我会把这个仓库 clone 到本地，然后通过软链接方式把 commands 目录映射到各个项目的.claude/commands/位置，这样改一处就能生效于所有项目。命令如下：
# 在项目根目录下执行 ln -s ~/projects/claude-code-templates/commands .claude/commands如果你不用软链接，直接把文件复制过去也行，但那样后续更新会很痛苦，不建议。
有一点要提醒：.claude/commands这个目录是否提交到版本库，取决于团队。如果团队希望共享这套规范，提交进去完全合理；如果只是个人习惯，建议 gitignore 掉，避免给队友制造噪音。
4.2 写模板时最容易忽略的细节：变量、引用和上下文长度
斜杠命令不是纯静态文本，Claude Code 支持在命令中引用上下文，比如$INPUT代表用户输入，$CLAUDE.md可以引用项目指令文件内容，你也可以显式引用其他文件。合理使用这些能力，能让模板的适用范围成倍扩大。
我自己用得最多的引用技巧是：在测试模板开头显式引用项目的测试配置文件，确保 AI 知道当前项目的测试运行方式。比如：
请先阅读 @tests/jest.config.js 了解当前项目的测试配置，再按测试模板执行。在 Claude Code 中使用@或$引用文件，能直接把文件内容注入上下文。这样一来，每个项目的测试风格即使有差异，模板也能自适应，不需要为每个项目单独维护一份。
还有一个细节：模板中关于"输出格式"的约束要具体到结构，但不要到措辞。比如"以表格输出，列包含：维度 / 评分 / 问题描述 / 建议"是好的约束，它会规范格式；但如果写"必须使用『问题分析』作为标题"，那是过度约束，会让回复变得生硬，反而丢失了自然语言的灵活性。
4.3 模板的迭代：基于真实使用日志做版本升级
模板不是一次性写好的，它需要随着使用不断迭代。我维护了一个简单的版本记录，每次改动都有原因。这套 claude-code-templates 如果说有什么"方法论"层面的东西，那可能就是：把模板当代码一样维护，有变更就用 git 记录，有改进就发布新版本。
我自己在迭代中主要依据三个来源：
- 使用后检查输出，看 AI 有没有遗漏我关心的点；
- 查看 Claude Code 的会话记录，统计哪些提醒我反复手动补充，这些就是模板"记忆缺口"；
- 和团队其他使用者交流，收集大家觉得"AI 经常做不好"的部分，反向补充进模板。
举一个实际的迭代例子：测试模板最初只有"生成用例"的步骤，后来我在使用中发现它生成的 mock 总是写得太理想化，没有覆盖资源释放这个点。于是我在模板里加了一条："所有涉及文件句柄、连接池、定时器的测试，必须验证资源释放分支。" 这个改进之后，测试质量又上了一个台阶。
5. 踩过的坑：过度约束、命令滥用与团队协作问题
模板体系用得好是杠杆，用得不好也会带来新的问题。这一节把我踩过的几个有代表性的坑写出来，帮你提前绕开。
5.1 模板不是越细越好：过度约束会让 AI 变成"机器"
我在早期犯过一个很典型的错误：为了让 AI 生成"100% 符合团队规范"的代码，我把模板写成了一本操作手册，每一步都规定得死死的。结果代码倒是规范了，但出现了新的问题——AI 失去了"灵活性"，遇到模板没覆盖到的情况时不会变通，产出反而更差。
举一个例子：我在测试模板里规定了"所有测试必须用 Jest 的describe三层嵌套"，但有一次需要给一个纯工具函数写单测，三层嵌套明显冗余。AI 因为指令约束，还是生成了两套嵌套，造成了阅读负担。后来我把这类硬性约束改成了"默认建议 + 允许判断"的表述，比如改为"通常使用三层嵌套，若被测函数逻辑简单，允许用单层结构，但需要在注释中说明理由"。
核心原则是：模板要约束的是"必须满足的目标"和"不能违反的底线"，而不是"每一步怎么做"。
5.2 斜杠命令的滥用：命令多了，反而不知道用哪个
我最初疯狂加命令，代码生成、接口设计、架构评审、数据库迁移、文档编写……目录里塞了二十多个命令文件。结果每次打开终端，我自己都要想一下该用哪个命令，最终反而削弱了使用意愿。
后来我做了减法，只保留真正每周都会用到的五六个命令，其他场景宁可现场写提示词。这个经历给我的启发是：模板的覆盖面不是越全越好，使用频率才是决定它价值的关键。如果你一个月都用不到一次的命令，它存在的意义不大，还可能和命令体系里其他文件形成干扰。
5.3 团队协作时的模板来源管理：同步、覆盖与信任问题
如果你在团队里推广这套模板体系，要注意一个比较隐蔽的问题：每个人的.claude/commands里的模板可能版本不一致。A 改了一句指令，B 那边没有同步，两个人执行同一命令得到不同的行为，这非常容易让人困惑。
我现在的做法是：模板仓库统一维护，发布版本走 git tag；各项目通过软链接或安装脚本固定到指定版本。每次模板更新后，在群里发一条简短的变更说明，让团队成员知道行为发生了哪些变化。信任问题才是最大问题——如果大家不确定模板的质量和更新原则，他们会倾向于绕过模板，直接手动编写提示词。所以模板的维护人要像维护开源项目一样，用心编写文案、留下变更记录、听取反馈。
5.4 模板互相冲突：CLAUDE.md 与命令文件之间的矛盾
最后是一个我自己磨合了一阵子才发现的坑：当 CLAUDE.md 里的规范和斜杠命令模板里的指令冲突时，Claude Code 会优先听从哪一个？这没有标准答案，取决于上下文顺序和具体表述。为了避免这种不确定性，我给自己定了一条纪律：全局规范只放"原则"，具体任务流程一律放在命令模板里，两者不建议描述同一个细节。
举个例子：不要在 CLAUDE.md 里写"所有测试生成必须用 Jest 编写"，因为测试命令模板里肯定也会写。两条都存在时，AI 可能会因为表述的微小差别产生行为偏移。整个模板体系内部的一致性，比每一份模板单独的正确性重要得多。
6. 从我自己的使用感受谈一谈：模板让你的 AI 协作真正可积累
说到底，claude-code-templates 这个项目的价值，不只是提供了一批好用的提示词，而是提供了一种思路：和 AI 协作的方式是可以被沉淀、被复用、被版本化的。
最开始用 Claude Code，我会觉得每次对话都是"一次性"的——用完就忘，下次再从头交代。有了模板体系之后，情况完全不同：我对 AI 的要求、标准、流程，都变成了仓库里可追溯的文件。今天发现 AI 在某个环节做得不好，我改一行模板，以后所有会话都受益。这种"复利效应"是模板给我带来的最大收益。
我个人实际使用中的体会是：真正值得模板化的，不是那些你说得清楚的需求，而是那些你经常忘记说清楚的事情。比如"测试必须覆盖边界条件""重构前先看影响范围""提交信息要写清楚破坏性变更"，这些要求你在第一次对话里大概率会提到，但每次都提又烦又累。把它们固化成模板，AI 每次都能做到，久而久之就变成了团队默认的工作习惯。
如果你刚开始尝试，我的建议是从一个最让你头疼的场景开始，比如测试生成或代码审查，写一份最简单的命令模板，用一周，改三版。这个过程会比你直接下载一百份别人的模板更有收获。毕竟，模板的价值不在于数量，而在于它是不是真的符合你的使用习惯。
