Claude Code 用久了最明显的感受不是模型懂多少而是每一轮新会话里你都在反复跟它解释同一个“怎么干活”的老问题。我刚开始用的时候喜欢把完整背景、硬性约束、输出格式全写在 prompt 里效果好是好但一天开十几次会话同样的话就得原封不动打十几次。后来实在受不了我干脆把所有高频场景下的用法整理成了一个独立项目也就是标题里的 claude-code-templates。前后折腾了差不多三周从最早的几个 Markdown 文件到现在可复用、可分发、可回溯的模板库它彻底改变了我的工作方式。这篇文章就是整个设计和落地的完整记录包括目录结构、配置拆解、能直接抄作业的模板示例以及我在真实项目里踩过的坑。正准备用 Claude Code 或者想把 AI 编码工具带进团队的朋友可以少走不少弯路。1. 我给 claude-code-templates 定的形态不是提示词合集是工作流资产先说清楚我最早犯过一个方向性错误以为模板库就是“一堆写得更好的 prompt”。我把十几个场景的提示词扔进一个文件夹用了两天发现效果提升有限该重复沟通还是重复该出错还是出错。后来我重新想了一轮才意识到问题出在分类方式上——提示词只是模板库的表层真正有价值的是把“工作方式”沉淀下来。1.1 什么应该由模板承接什么不应该我的判断标准很简单模板应该承载的是“稳定的、可迁移的做事规则”而不是“一次性的具体内容”。比如“代码审查时应该按什么顺序检查、哪些问题必须停下来追问、哪些地方只提示不修改”这类规则是稳定的适合沉淀而“这次要审查的是哪个分支、改动了哪几个文件”这类具体信息应该由使用者在调用模板时临时补充。我见过有人把模板写成这样“请检查 src/user.ts 的第 45 行这个函数有 bug。”这种模板一次能用下次数据一变就作废。真正的模板应该是你是一个做过多年 Code Review 的资深工程师。请先了解本次改动的文件和 diff再按下面的清单逐项审查最后以指定格式输出结果。具体文件、具体行号交给会话里的当前上下文模板只负责审查流程、审查规范和输出要求。这么一拆模板的复用率一下就起来了。1.2 筛选场景的四个判断标准不是什么场景都值得做模板。我整理 claude-code-templates 的时候只给满足下面四个条件的场景做模板判断维度具体要求我实际落地的例子发生频率一周至少出现两三次代码审查、重构、写提交信息上下文强度需要交代大量背景才能让模型干对活调试、遗留代码文档化质量难以衡量结果好坏依赖做事顺序不依赖单一答案重构安全性检查、测试覆盖评估团队可共享一个人用的流程别人也能获益提交规范、目录约定、命令使用规则用这套标准筛了一遍我身边日常能沉淀的场景大概就七八个其中六个我反复打磨过后面会展开写。剩下的场景比如“帮我想个函数名”“解释这段代码”太轻、太个性化模板反而显得笨重。1.3 模板库和普通提示词文件的关键差异模板库不是提示词仓库的换皮至少有三点差异第一模板库有明确的生命周期管理。每个模板有版本号、修改记录、适用条件甚至能回滚到上一个版本。临时 prompt 是写了就忘模板是改了要留痕。第二模板库对输入输出有约束。普通提示词可以任意发散模板必须规定需要使用者提供什么输入模型应该给出什么结构的结果哪些边界条件算“任务完成”。第三模板库要能批量交付。靠复制粘贴没法推广必须有一个安装、更新、校验的机制让团队里每个人拿到的都是同一套规则。这三点说起来简单落地的时候牵扯到配置、目录、脚本一堆细节下面分步讲。2. 骨架与配置分层 CLAUDE.md、斜杠命令、输出约束使用 Claude Code 的时候真正决定模型长期表现的不是闲聊式对话而是它在每轮工作前能读到什么。Claude Code 本身支持读取 CLAUDE.md 文件作为项目记忆也支持通过自定义斜杠命令快速唤起一组复杂指令。claude-code-templates 的核心骨架就是把这些能力组合起来。2.1 记忆分层全局、项目、任务三级各放什么我给它们定的边界非常明确互不打扰。全局层对应~/.claude/CLAUDE.md放的是“无论面对什么代码库都成立”的个人偏好比如默认使用中文回复、涉及删除操作必须二次确认、对不确定的问题先承认不确定性再给出假设。项目层对应仓库根目录的CLAUDE.md放的是这个项目特有的长期事实比如技术栈、目录职责、构建命令、测试方式、代码风格约定。这一层是模板库自动带入上下文的入口我不需要每次说话都重复“这是一个 NestJS 项目用 pnpm 管理依赖”项目里的 CLAUDE.md 会替我说。任务层对应.claude/commands/目录下的模板文件放的是一件事怎么做怎么审查怎么重构怎么调试。任务层的文件不会默认进入每轮上下文只有我主动用/xxx命令触发时才会完整加载这正好解决了“全局塞太多内容导致 token 浪费”的痛点。三个层级的分工很清楚全局层管风格项目层管事实任务层管操作流程。模板库主要建设的是任务层但前两层如果没有理清任务层再精致也容易带病运行。2.2 斜杠命令是模板的真正入口我把一条模板做成一个斜杠命令。命令文件的格式是 Markdown文件头部可以写 YAML 元信息正文就是给模型的指令。它的运作逻辑很直接你在 Claude Code 里输入/review它就自动读取对应的命令文件把整段指令作为系统级上下文传给模型。以我的一个命令文件为例--- description: 对当前改动执行一轮代码审查 agent: false allowed-tools: Read --- 你是一名拥有 10 年以上工作经验的代码审查者。 第一优先理解改动意图 - 先读取 git 状态、git diff 和涉及文件的历史背景 - 如果差异过大先向使用者确认本次改动范围 第二优先按清单逐项检查 1. 逻辑正确性分支条件、边界值、异常路径 2. 安全性输入校验、权限判断、敏感信息泄露 3. 性能循环嵌套、无意义的重复计算、不必要的大对象持有 4. 可维护性命名、函数长度、重复代码 约束 - 只输出问题清单不要直接把修改后的代码写出来 - 问题按严重程度分为 P0/P1/P2P0 表示必须修复 - 如果清单中的某个项目不适用明说“不适用”不要编造注意元信息里的agent: false意思是这个命令不需要切换到多步代理模式只要求单次阅读和审查避免模型自作主张跑去改代码。allowed-tools限定它只能用读取工具这是第一道安全阀。这个设计解决了一个很实在的问题我不需要在对话里事无巨细描述“你要做什么”只需要一条/review整段专业流程就稳定地加载了。2.3 输出格式与退出条件的强制约定模板容易失控的地方是“让模型自己决定怎么输出”。一旦允许自由发挥同样的服务端逻辑今天给你列条明天给你写整段后天给你画个表格后续要把它接进脚本做统计就会非常痛苦。我在每个模板里都固定了输出框架。比如审查类模板强制要求输出这样几块## 结论 一句话结论本次改动是否可以合并风险等级如何。 ## 问题清单 - [P0] 问题简述 / 文件位置 / 依据 / 建议 - [P1] ... - [P2] ... ## 未检查项 列出本次因为条件限制没有覆盖的部分如未运行的测试、未查看的历史提交。固定输出格式有两层价值。第一层模型知道往哪个方向收敛不会东拉西扯第二层我可以写脚本去扫描会话输出统计每次审查发现的 P0/P1 数量模板库的效果就有了量化依据。这一点在团队推广时特别重要否则你永远只能用“感觉更好用”来向同事解释。除了输出格式还必须定退出条件。很多模板没有告诉模型“做到什么程度算完”结果模型把简单审查无限延伸开始给你报代码风格建议真正致命的逻辑问题反而放过了。我在模板末尾都会写清楚当问题清单和结论都已输出后任务即结束。不要补充无关建议不要重写代码。模板是给做事流程立规矩不是给模型自由发挥的舞台。这个认知后面帮我避了好几个大坑。3. 可直接抄作业六类高频场景的模板设计这一节我把自己打磨过并且一直在用的六个模板拆开讲。每个模板都会说明设计思路、核心指令和边界条件你拿到之后改改项目名和技术栈就能用。3.1 代码审查模板只点评不代写开头已经展示了/review的主要结构这里补充几个我在实战中不得不加的细节。第一个细节是“先读历史再下结论”。有几次模型直接看着 diff 说“这里没错误”但改动涉及的历史 bug 修复完全没有纳入考虑。我后来在模板里强制加了一步在输出结论之前必须先检查 git log 中被改动文件的最近提交记录。 重点确认是否存在此前反复修改过的逻辑区域。这一步非常值得因为 AI 擅长盯住表象问题却容易忽略“这个文件为什么长成这样”的演进脉络。第二个细节是严格禁止“自动改代码”。审查和修改是两件事一旦让模型在审查的同时给出修改方案它很容易越权甚至连带产生新的风险。所以我的模板反复强调审查只输出问题和建议不直接产出修改后的代码。真正要改的时候重新调用/refactor命令。3.2 重构模板带安全网的渐进式改造重构是 Claude Code 最容易翻车的场景。模型太喜欢一次性给你一版“更优雅”的整体重写但这种输出几乎没法在真实代码里落地一贴就会引入大量回归 bug。我的/refactor模板是这样设计的--- description: 在保持行为不变的前提下执行一次渐进式重构 agent: true allowed-tools: Read, Edit, Glob, Grep --- 你是一名重构经验丰富的工程师。你的目标是在不改变外部行为的前提下提升代码可读性和可维护性。 第一步定义安全边界 - 识别被重构代码的入口和出口 - 列出所有现有的测试用例并指出哪些能覆盖这次改动 - 如果没有测试覆盖明确告诉使用者必须先补测试 第二步小步重构 - 每次只改一个逻辑点不要同时调整命名、结构和算法 - 每次修改后说明影响范围、可能受影响的调用方、验证方式 第三步提交提示 - 为每个独立重构步骤生成可单独提交的 git commit 信息最关键的是“先补测试再动手”。我把这条写在模板靠前的位置因为 Claude Code 默认没有强烈意愿去写测试它会觉得直接改代码更快。但真实的重构经验告诉我们没有测试网的重构就是在走钢丝。另外我在模板里设置了agent: true允许模型调用多步工具去搜索引用、读取文件、逐步修改。这和审查模板刻意相反说明模板工具本身应该根据任务灵活切换不是所有场景都要限制。3.3 故障调试模板锁定嫌疑区而不是瞎猜调试类任务最怕模型“猜”。看到报错日志直接说“这可能是数组越界你改一下”。结果你改完一跑报错还在浪费一轮时间。我的/debug模板把整个排查链路分成了四步1. 还原现场读取报错信息、堆栈、输入数据明确复现条件 2. 建立假设列出 3 到 5 个可能导致问题的嫌疑点并给每个嫌疑点一个排除证据 3. 逐项排除按嫌疑从高到低读取相关代码或执行小范围验证 4. 定位根因只有在证据充分时才输出根因结论和修复建议我在模板里给了一个关键词叫“证据优先”。模型在调试时的本能是“快速给答案”而模板的作用是逼它先给证据链。这条规则显著减少了“看似对、实则隔靴搔痒”的调试结果。实际使用中我还加了 一条如果你无法在 3 轮工具调用内定位根因请把当前进展输出给使用者询问是否继续扩大排查范围。这一步是为了防止模型在一个错误方向上无限深挖带偏整个会话节奏。3.4 测试与回归模板产出可追踪的覆盖报告写测试这件事很多开发者自己不乐意做模型也不会主动给自己找活干。所以我专门做了/test模板把它变成一个固定仪式。--- description: 为指定模块补充测试并输出覆盖报告 agent: true --- 请为当前模块设计测试策略。 第一明确被测对象模块的公开接口、核心函数、边界条件。 第二参考项目已有测试风格不要发明新的测试模式。 第三补充缺失用例重点是 - 正常路径 - 空输入 / 非法输入 - 边界值 - 异常分支 第四用项目现有的测试命令执行全部测试并报告结果。 输出要求 - 列出本次新增的测试用例清单 - 对整个模块给出覆盖薄弱点的判断 - 不要为了覆盖率而编写无意义的断言这个模板的价值不在于替你把测试写完而在于它把“测试策略思考”前置了。模型会先描述模块的外部行为再写用例生成的测试质量明显高于那种“看到函数就顺手补一句 assert”的随手产出。我还定了一个硬规则新增用例必须和项目原有测试风格一致。有些团队用 Jest有些用 Vitest有些喜欢 describe/it有些喜欢 test模型默认会选择最常见写法模板必须强制它跟着现有习惯走。3.5 提交信息模板把团队规范揉进单条命令一个很轻但收益很实在的模板是/commit。每个项目对提交信息格式都有要求有的要求带需求单号有的要求类型前缀这些规则写进模板后每次提交都稳定格式化。--- description: 生成符合团队规范的 git 提交信息 agent: false allowed-tools: Read --- 请根据当前 git diff 和 git status 生成提交信息。 规范 - 格式type(scope): subject - type 取值为 feat / fix / refactor / docs / test / chore - subject 使用简体中文不超过 50 个汉字结尾不加句号 - 正文部分说明为什么做出这个修改而不是做了什么 要求 - 先读取 diff理解真实改动内容 - 如果 diff 范围过大拆分出多个建议提交 - 一次提交只表达一个原子改动不要混写无关内容这里有个小技巧命令的正文自然语言是给模型的指令description 字段则是给使用者看的命令提示两个地方都要写清楚一个给机器一个给人。3.6 遗留代码文档化模板先梳理行为再动笔给老代码补文档最容易出现的问题是模型照着代码表面写文档等于把代码翻译成文字读者依然看不懂。我的/docs模板要求模型先“重建行为模型”再动笔1. 从调用入口开始画出模块的输入输出链路 2. 列出所有外部依赖和副作用数据库、缓存、文件、第三方接口 3. 找到代码里隐含的业务规则如状态机、超时时间、重试策略 4. 文档结构必须包括模块职责、关键流程、边界情况、变更注意事项这一条的难点在于“隐含规则”。模型往往意识不到某个魔法数字背后的业务含义我在模板里专门加了引导语“如果代码中存在无法解释的常量或条件分支请明确标注为需向原作者确认。”这比让模型强行编一个解释安全得多。4. 仓库结构、版本分发与团队协作接入模板写在本地是一回事能安装到不同机器、能跟着团队一起演进是另一回事。claude-code-templates 走到第三周时我已经把它重构成一个标准的 Git 仓库配合脚本做分发。4.1 我最终采用的仓库目录直接看我当前维护的仓库结构claude-code-templates/ ├── CLAUDE.md ├── README.md ├── CHANGELOG.md ├── commands/ │ ├── review.md │ ├── refactor.md │ ├── debug.md │ ├── test.md │ ├── commit.md │ └── docs.md ├── scripts/ │ ├── install.sh │ ├── verify.sh │ └── stats.py ├── docs/ │ ├── conventions.md │ └── guides/ └── versions/ └── v1.2.0/根目录的 CLAUDE.md 是给“未来准备接手维护这个模板仓库的人”看的它的作用是告诉维护者命令文件如何命名、frontmatter 里必须包含哪些字段、模板的更新流程是什么。这就是“元模板”——用 Claude Code 的方式管理 Claude Code 模板。commands/是模板主目录每个文件对应一条斜杠命令。scripts/里放安装、校验、统计脚本。versions/是发版时生成快照的目录正常开发不太需要手动碰它。4.2 模板的版本标识与变更流程模板是会被反复引用的“代码”它同样需要版本管理。我规定每个命令文件头部必须写清楚版本号--- description: 对当前改动执行一轮代码审查 version: 1.2.0 last_updated: 2025-01-10 ---版本号的作用在团队场景里非常明显。有同事问我“你现在的 /review 是不是比上周改过了”只需要把版本号亮出来就能对齐不需要逐字对比内容。变更流程我定成三条影响判断的变更比如增加了审查检查项必须至少提升一个 minor 版本不能悄悄改。每次变更在 CHANGELOG.md 里留一行写明变化点和原因。禁止在未通知的情况下删除某个命令文件必须废弃就保留文件并标注 deprecated。这套流程不会增加多少负担但能让模板库在多人维护时不乱。当然了如果你只是一个人用流程可以砍半但至少版本号和 changelog 建议留着。4.3 团队接入的最小成本方式团队接入的最大障碍不是模板内容而是“我凭什么要用你的方式干活”。为了降低接入成本我写了一个安装脚本同时也提供了手动复制两种方式。安装脚本的核心逻辑很简单就是把 commands 目录里的文件软链接到用户的~/.claude/commands/下#!/usr/bin/env bash # scripts/install.sh set -euo pipefail TEMPLATE_DIR$(cd $(dirname $0)/.. pwd)/commands TARGET_DIR${HOME}/.claude/commands mkdir -p $TARGET_DIR for file in $TEMPLATE_DIR/*.md; do name$(basename $file) ln -sfn $file $TARGET_DIR/$name echo linked $name - $file done echo done.软链接的好处是模板仓库更新代码后使用者下一次触发斜杠命令时自动读取的是新版本不需要手动同步。缺点是如果你不打算让远程仓库的变更立刻影响本地行为请换成 copy 而非 symlink。这取决于团队管理风格——我们团队选择了 symlink因为想让“模板版本统一”成为默认状态。团队接入还应该配一个简单的 README告诉同事模板到底覆盖哪些场景。我见过最好的方式是在 README 里提供一张速查表命令触发场景输出物/review提交代码前或合并请求中问题清单 风险结论/refactor重构非核心模块时分步安全改动 提交信息/debug出现未知 bug 时证据链 根因定位/test需要补充模块测试时策略说明 新增测试 覆盖报告/commit准备提交时规范提交信息/docs给遗留代码补文档时行为模型 结构化文档这张表不用太长但足以让不了解模板的人一眼判断“我这个场景该不该用”。5. 实测翻车的三个坑与修复链路模板库不是搭好就完事实际跑起来问题一堆。下面这三个坑是我自己踩过的每一个我都给还原一下当时现象和排查过程不直接甩结论。5.1 上下文过载什么都想写进模板结果每轮都在烧 token第一版模板我写得非常“大而全”每个命令都恨不得把公司业务背景、编程规范、项目架构、用户偏好全塞进去。结果很直接每次触发命令上下文占用暴涨响应变慢而且模型开始被大量背景信息淹没反而忽略了当前代码的实际问题。排查过程让我意识到问题在于“层级混淆”。项目长期信息应该放在项目根目录的 CLAUDE.md 里而不是塞进任务模板。任务模板应该只负责“这件事怎么做”不该反复重复“项目用什么框架”。修复方式是做一次信息拆分把所有项目常识类内容移出命令文件只保留流程规则和审查清单。实际效果是同样的 /review 命令上下文占用降了大约三分之一响应准确性反而上升了。这里我总结出一个经验模板信息的密度和任务质量不是简单的正相关信息太挤会稀释模型对核心指令的注意力。模板宁可短而明确也不要长而全面。5.2 约束反噬AI 把模板当教条低级判断都不做了第二个翻车现象出现在模板里的约束过多之后。我的 /refactor 模板原本写了很多“不要做”的禁令比如“不要调整公共接口签名”“不要修改缩进风格”“不要动配置文件”。结果模型变得极度保守遇到真正应该修改公共接口的情况也不敢动了它宁可不做也好过违反模板指令。有一次重构中某个内部函数已经是明显的坏味道正确做法就是改签名并同步所有调用点但模型面对模板里的禁令直接告诉我“按模板约束这个改动超出范围”。我当时挺无语排查到最后发现问题不在模型能力而在模板的约束粒度太粗。修法是把“一刀切禁令”改成“附带判断条件的约束”约束 - 默认不修改公共接口签名但如果现有签名阻碍了本次重构目标请明确指出并说明前置影响后再动手。 - 不要调整无关文件的格式如果工具自动格式化误伤请精确回退。给约束加上例外判断模型才有空间在真实场景里做合理裁决。这个坑特别值得注意因为模板最初的初衷是规范行为但过度规范会反过来削弱模型的使用价值。我后来加了一条总原则在所有模板里“模板规则是默认行为现实冲突时以现实为准但你必须把冲突点输出给使用者确认。”这条原则现在仍然保留。5.3 输出格式过度精确模型生成的伪结构化输出更难解析第三个坑来自我“强制结构化”的执念。初版模板要求每个输出必须是严格的 JSON{result: PASS, issues: [{level: P0, ...}]}我用一周后发现模型经常产出一段夹杂着解释文字的 JSON甚至偶尔在 JSON 后面追加“不然呢”之类的自然语言结尾。反而更难解析我用脚本去抓 JSON不但要处理外层杂质还要容忍字段缺失。排查之后我的结论是让模型输出 JSON 格式没问题但别要求它不用 Markdown 包裹也别禁止任何额外解释。更好的做法是允许它先给出自然语言结论再附加结构化数据区我用脚本只提取标记区块。比如## JSON_RESULT { ... } ## END同时脚本侧做好容错解析失败时主动回退到整段文本提取关键信息。这件事教会我一个原则模板的输出规范要照顾模型的生成习惯而不是单纯从“机器解析方便”出发。模型生成和脚本解析是同一个系统的两端设计时必须同时考虑。6. 我把模板库再往前推一步统计、反馈与轻量自动化到了这一步模板库已经能稳定解决日常问题。但我发现它还有两个隐藏价值没有榨干一是用数据告诉大家模板到底有没有用二是把模板库自身的健康度变成可观测指标。所以我加了统计脚本和反馈机制。6.1 用量统计靠日志也靠输出锚点我没有在 Claude Code 内部埋点而是用了一个笨办法。所有模板输出都带有固定锚点比如审查模板输出## 结论测试模板输出## 测试结果我可以直接翻历史会话记录统计每个模板被调用的次数和结论分布。这个方式不需要接入内部 API纯粹基于文本扫描成本低也足够用。配合scripts/stats.py能生成一张每周用量表格# scripts/stats.py import re, collections, glob logs glob.glob(~/.claude/projects/**/*.md, recursiveTrue) counter collections.Counter() for path in logs: text open(path, encodingutf-8, errorsignore).read() for key in [review, refactor, debug, test, commit, docs]: counter[key] len(re.findall(f/{key}\\b, text)) for k, v in counter.most_common(): print(f{k}: {v})数据出来以后我立刻发现commit模板是最常被触发的debug模板使用率最低。一开始觉得奇怪后来一想也合理——大家提交代码次数多调试反而更依赖自己读日志不太愿意让模型介入。于是我有意识地在debug模板上投入更多精力推广因为那正是模型能帮上大忙的场景。6.2 反馈回路遇到模板不好使就当场记一笔模板不可能一次写好我养成的习惯是“当场记问题”。每次觉得某个命令的输出不对劲就在一个固定的反馈文件里追加一笔2025-01-10 /review跨文件改动时没有读取调用方上下文导致误报。这个反馈文件积到 20 条左右我再集中修一轮模板。修完删除对应条目避免问题反复出现。这比每周复盘更即时也不依赖记忆属于成本最低的改进机制。反馈文件也会共享到团队仓库同事发现问题可以直接提不需要等我来收集。模板库的进化不再靠某一个人的灵感而是靠每个人日常使用中的触觉。6.3 可以把模板库再往前推一步的扩展方向目前我做的还是“规则驱动”的模板下一步我想把模板和自动校验串起来。具体来说在代码审查模板里嵌入项目自定义的 lint 规则输出让模型先跑工具再结合工具结果做判断而不是只靠阅读代码。另一个方向是把模板按“任务难度”分成轻量和深度两档。轻量版给简单任务深度版用于高风险重构或跨模块改动。这套分级目前在实验预期能进一步降低低风险场景的 token 消耗。最后分享一个我个人的体会模板库最大的价值不在于省了多少打字时间而在于它把你脑子里的“隐性知识”变成了团队里看得见、改得动、吵得起来的“显性规则”。这个转变一旦完成AI 编码工具的使用水平就会从一个工程师的私房技巧变成一个组织可积累的能力。以后哪怕有同事离职或者项目换人这套做事方式还能继续留在仓库里这就是我折腾 claude-code-templates 最值得的部分。
