1. 为什么我会开始整理claude-code-templates从提示词碎片到模板库先说一个我自己的真实场景。过去几个月我几乎每天都要在终端里和 Claude Code 打交道从需求分析、代码重构、模块设计到提交信息整理。有一段时间我发现自己在一个反复犯的低级错误里打转同一个项目昨天我刚跟它解释清楚代码规范、目录结构、测试要求今天换个任务又得重新讲一遍同一个团队协作仓库每个人用 Claude 的方式五花八门有人给一段指令就让它改代码有人塞进去五十行上下文结果模型读都读不完。最让我崩溃的一次是做一个涉及三个子模块的接口重构。我连续跟同一个会话对话聊到后面上下文里塞满了历史输出模型开始出现“记性错乱”明明前面已经确认过的模块边界到了后面又开始“重新发现”。一气之下我把当天所有重复用到的指令、约定、输出格式全部翻出来开始做一件本该早点做的事把零散提示词沉淀成一套有结构、可复用、能跨项目套用的 claude-code-templates。说实话这个思路并不是什么新发明它本质上跟“把常用函数抽出来复用”是一个道理。只是很多人一开始用 Claude Code 时会天然把它当成一个“聊天窗口”而不是一个“可编程的工程工具”。你今天想让它写测试就即兴说一句“给我写几个单元测试”明天想让它做代码审查又来一句“帮我看看这段代码有什么问题”。这两句话本身没有任何记忆也不会相互配合更不会积累对项目的理解。而模板库要解决的恰恰是这三个问题第一减少每次重新描述的成本第二把不确定的行为变成确定的输出第三让协作的每一个人拿到同一套行为基准而不是各自跟 AI 对话、各自发挥。我整理 claude-code-templates 的过程跟我以前整理 dotfiles 配置文件很像。不是上来就搞一个庞大的体系而是从最频繁的动作切入把每一次重复的提问“显式化”先文档化再参数化最后版本化。这个过程坚持一两个月之后你就会明显感觉到一个区别以前是你追着 AI 把需求讲清楚现在是 AI 按照你制定的协议主动把活干完而且干活的路径大体可控。这篇内容不是官方文档翻译也不是什么吹捧工具的文章就是一个普通开发者在真实项目里把 Claude Code 模板化之后总结出来的实践经验、目录设计、写作方法和踩坑记录。适合已经用过几天 Claude Code、但对“怎么系统化使用”还有点模糊的人也适合团队里正在推广 AI 编码助手、想统一大家使用方式的同学。2. 搭建骨架目录结构、记忆文件与模板加载机制2.1 三类记忆文件怎么分工Claude Code 的模板体系底层依赖一套记忆文件机制。你可以简单理解为Claude 在启动时会自动读取一些 Markdown 文件把它们作为“项目背景信息”的一部分加载到上下文里。这套机制有三个层级决定了你“往哪里放模板”用户级记忆文件默认位于~/.claude/CLAUDE.md。它适合放跨项目通用的规则比如你希望所有项目都遵守的代码风格偏好、常用的输出格式约定、不愿意让 AI 做的事情等等。项目级记忆文件通常放在仓库根目录文件名也叫CLAUDE.md。它适合放当前项目的背景比如项目的技术栈、模块划分、构建命令、测试方式、目录约定。目录级记忆文件可以在子目录里再放CLAUDE.md用于限定某个模块或目录内部的行为边界。适合比较大的 monorepo不同子项目有完全不同约定的时候使用。我一开始犯的错是把所有东西都往一个 CLAUDE.md 里塞。结果文件越写越长几百行的东西每次启动都要全部读进去上下文被占掉一大块而且不同内容之间还互相干扰。后来我学聪明了记忆文件只负责“索引”实质性的长模板放进独立文件用导入语法按需加载。2.2 斜杠命令模板的最自然载体Claude Code 中有一种斜杠命令机制把.claude/commands/目录下的 Markdown 文件暴露成/命令名的形式。这几乎是模板系统的主干。比如目录里放一个security-review.md文件开头写几行 frontmatter提供命令描述下面就是模板正文。使用时直接输入/security-reviewClaude 就会加载这个模板然后根据你当前对话的上下文执行里面的要求。这个机制之所以重要是因为它把“写一段提示词”变成了“调用一个命令”。命令有名字、有描述、有确定的执行逻辑。你不需要每次把一整套要求打出来只需要输入斜杠命令名这就是模板库的第一层抽象。2.3 按需加载比一次全加载更重要很多人理解“模板”两个字就以为要把所有模板一次性告诉 Claude。实际上这是彻底的误解至少在 Claude Code 的体系里最终效果会很差。原因很简单上下文窗口是有限的公共资源你塞进去 30 个模板看起来功能齐全实际上每个模板都被稀释了模型在复杂任务里根本不知道该优先遵守哪一套。正确的做法是常用全局习惯放进用户级记忆项目特有信息放进项目级记忆而具体任务的执行规范放到斜杠命令里用哪个调哪个。这就好比一个工具箱箱子本身放在固定的位置但你要拧螺丝时才拿出螺丝刀而不是把整套工具都焊在手上。对模板库的目录设计我的习惯是这样~/.claude/ ├── CLAUDE.md └── commands/ ├── refactor-safe.md ├── code-review.md ├── test-coverage.md ├── pr-summary.md ├── trace-bug.md └── doc-update.md项目内部出现特有规则时再在仓库里加CLAUDE.md和.claude/commands/。目录本身不复杂复杂的是里面每个模板的写作质量。这也是我接下来要重点展开的部分。3. 写模板不等于写提示词结构、变量与显式协议3.1 先分清“聊天提示词”和“模板”的本质区别不少人跟我说模板不就是把提示词存到一个文件里吗这种想法我敢说做出来的东西绝对不好用。聊天提示词是给人看的讲究自然语言表达模板是给模型执行的协议讲究可预期、可校验、可重复。聊天提示词里说一句“帮我看看这个代码注意一下性能问题”模型确实会给你反馈。但每个人说“注意一下”的标准完全不一样你在模板里如果也写这种模糊词那这个模板执行起来就是碰运气。典型的现象是同一套模板今天跑和明天跑行为差出十万八千里。所以在设计模板的时候我强制自己把每个模糊词汇翻译成可验证的行为。比如“注意性能问题”要拆成“分析循环内是否有重复计算、是否创建了不必要对象、能否用缓存机制优化”。模型是按字面意思执行的你把边界划得越清楚它的行为就越稳定。3.2 用“任务-背景-产物-约束”四段式组织模板经过多次迭代我把模板的正文固定成四个段落。这不是唯一的写法但对我来说是性价比最高的一种结构任务描述一句话说清楚这个命令要完成什么交付。背景引用明确告诉 Claude 应该去读哪些文件、依据什么上下文。产物清单规定最终输出的形式比如修改哪些文件、新增什么测试、报告包含哪些章节。约束边界列出不允许做的事情或者需要先确认再执行的情况。给一个我实际在用的简化示例文件.claude/commands/refactor-safe.md--- description: 安全重构当前选定的函数或模块保持对外行为不变 --- 你的任务是完成一次“行为保持”的重构只改变代码内部结构不改变任何外部可见行为。 背景 - 通读项目根目录的 CLAUDE.md理解全局约定。 - 找到当前对话上下文中被用户提及的目标函数或模块并通读其完整实现。 - 如果上下文没有明确指定目标先列出疑似可重构的候选清单然后向用户确认。 产物 1. 输出重构后的完整代码块。 2. 说明本次重构做了哪些结构调整。 3. 指出重构前后测试用例是否需要变更。 4. 如果有行为差异风险用列表明确标出。 约束 - 不允许修改公共 API 签名除非用户明确要求。 - 不允许顺手修复无关 bug若有发现单独报告。 - 不要在没有测试文件的项目里强行生成测试文件先询问用户。你看出来区别了吗这个模板不是在“命令模型”它是在“给模型立规矩”。每一句话都是可执行的指令没有“尽量”“可能”这种留白。留白留给模型自由发挥的部分反而不多因为它们往往会导致输出千奇百怪。3.3 模板里的“输入变量”要显式声明另一个常被忽略的问题是模板怎么接收用户输入。斜杠命令被触发时用户可以在命令名后面追加内容比如/refactor-safe authService.ts。模板正文里怎么拿到这个“authService.ts”我的惯例是在模板里写一段“入参说明”告诉模型应该从当前对话上下文的哪部分提取目标。给个例子在 refactor-safe 模板里我会加一行“如果冒号后面紧跟了文件路径优先以此路径作为重构目标如果没有则询问用户。”这样就把模板从“死文本”变成了“支持参数输入的半自动协议”。更复杂的参数化可以在模板里定义一套轻量记号。比如用{{目标文件}}、{{验收标准}}这样的占位符让使用者在复制模板自己维护的时候能快速替换。对 Claude 本身来说它不需要这套占位符也能理解你的意思但占位符对你维护模板有意义它帮你一眼看出模板里哪些位置是需要人工补充的。4. 实战模板库的沉淀过程从一次性任务里提炼高复用资产4.1 不要凭空设计模板要从真实任务里反推很多人整理模板容易犯一个毛病坐在那里脑补“AI 应该需要哪些模板”然后花一下午写出二十个文件用的时候发现一半没用上。我的意见是别搞这种拍脑袋式设计。我是一个个星期反推出来的每次用 Claude Code 做任务如果发现这个任务跟我上周做过的一个任务高度重复我就打开终端历史把那两段提示词放在一起对比提取出共同的部分、差异的部分共同部分放进模板差异部分定义成变量。用这个办法我第一个整理出来的模板不是代码审查也不是重构而是“提交信息生成”。因为我发现每天有大量时间花在写 commit message 上而团队又有自己的提交规范。第一版模板很简单就是把提交规范的几个 key 点写进去再加上一句“请根据 git diff 生成三条符合上述规范的候选提交信息”。后来用了几次发现模型经常不看 diff 就开编于是加了一条强制约束“必须先读取git diff的输出在输出里引用实际变更的文件名再生成消息。”以此为起点我的模板库沉淀下来几类特别值得做的命令。这里挑我个人认为复用率最高的几个分类来说。4.2 代码审查类模板的三个关键设计代码审查是我认为最有必要模板化的场景之一。原因很简单很多开发者的日常 AI 使用代码审查是最频繁的日常任务。它最大的风险是模型输出“看起来很有道理但实际上什么都没说”的套话比如“建议考虑更好的错误处理”。我的 code-review 模板里强制设定了三步流程。第一步模型必须列出本次审查涉及的所有文件清单第二步对每个文件做逐行风险扫描时必须引用具体的行号和代码片段不允许给出没有依据的泛评第三步所有问题必须按严重程度分级且每个“高严重度”问题必须给出可执行的重构建议代码块。这套设计逼着模型把模糊的“我觉得有问题”变成“这里第 47 行在事务提交前返回可能导致连接未释放”。实测下来质量提升非常明显至少不会再出现满屏的正确废话。4.3 问题排查类模板为什么要强调“证据链”另一个复用率很高的是问题排查模板。Claude Code 在终端里能看到报错堆栈也能读取日志文件但如果你不约束它它就会直接跳到“可能是 XX 问题建议尝试 YY 方案”这一步跳过了它自己对证据的收集过程。我的排查模板里设了硬性要求复现路径优先要求模型先输出复现步骤哪怕是推测性的也要按“假设-验证”的顺序描述。证据优先于结论所有结论必须引用日志片段、堆栈帧、配置文件里的具体关键词。禁止在收集证据之前抛出修改方案这个约束很粗暴但很有效它把模型从“猜测模式”切到“侦探模式”。用上这个模板之后我发现排查 bug 的返工率降了不少。原来常常是模型给了三个建议你挨个试完发现都不对现在它会先跟你确认证据链证据不足时会主动要求你提供更多信息而不是瞎猜。4.4 文档生成模板与知识沉淀还有一类很容易被忽略的模板是文档类。代码仓库里最常见的需求是“给这个模块写 README”“更新这个接口的文档”“生成变更记录”。这类任务看起来简单实际上模型最容易自说自话。我为文档任务设计的模板里必带一条内容边界规则只允许依据代码实现和已有注释撰写文档不允许“充分发挥想象”。同时要求模型在文档里标注每个关键部分的来源文件这样审查文档的人可以快速核实。这套文档模板再加上前面说的斜杠命令机制基本成为了团队里推广 AI 编码助手时的“入手三件套”。新人拿到这套 claude-code-templates不需要记一堆复杂的提示词技巧只需要知道/code-review、/trace-bug、/update-doc三个命令就能用出相当规范的效果。5. 测试与迭代让模板进化而不是腐烂5.1 模板的“单元测试”其实不复杂有人说写模板要测试我觉得这是误解它没有像代码那样严格的单元测试体系但确实需要做“回归验证”。做法也很朴素拿一个之前已经完成过的真实任务把当时的上下文场景还原出来用新改的模板重新跑一遍对比两次输出。凡是模板改完之后结果反而变差的立刻回滚。我几乎每次调整模板前都会建立一个简单的记录。你不用搞复杂的工具一个 Markdown 文件或者一个表格就行模板名测试任务期望输出实际结果结论refactor-safe提取某 API 到独立服务不修改公共签名通过保留trace-bug排查登录接口超时输出证据链完整缺少复现步骤需补充这种方式跑两三个月之后哪个模板是有效的、哪个是鸡肋数据里看得清清楚楚。5.2 模板膨胀的威胁目录里文件越多维护成本越高随着模板数量增长你会遇到一个新问题维护成本呈指数上升。很多命令之间会出现重叠比如 code-review 里也要检查安全性security-review 里也要看代码质量。这时候如果你不做收敛模板之间就开始互相矛盾同一个项目在两个命令下会得出不同的结论。我的做法是设置一个“每月一清”的节奏。每个月把模板库过一遍凡是在过去 30 天里没有被实际调用过的命令移入 archive 目录凡是职责重叠的命令合并成一个。这个动作看起来简单但它保证了模板库永远保持着可维护的体量而不是变成一个无人敢动的怪兽。5.3 不要在模板里写“永远正确”的正确废话还有一个测试中经常暴露的问题。不少模板写了两天之后表面看起来好像挺合理实际上一执行就露馅。典型症状是模板里的要求完全正确但模型执行了两轮就开始“偷工减料”。比如模板里写“请全面审查代码质量”模型会默认你只是客气一下于是给个五分钟跑完的泛泛而谈。原因不是你写得不清楚而是这句话没有可校验的交付物。模板里必须出现类似“输出一个表格每行对应一个文件至少包含 3 个风险项”这样可以直接检查的硬性要求。可校验才算合格的模板。5.4 让模板在团队里“对齐”也需要协议如果只有你自己使用那模板怎么定都无所谓。但一旦要推广到团队就会遇到“适配性问题”。不同人的使用习惯不一样有人喜欢让 AI 直接改文件有人只希望 AI 给建议。模板里如果没定这方面的细节就会出现同一条命令在不同人手里行为不一致的情况。我后来在模板库的根目录加了一个全局约定文件叫TEMPLATE-GUIDE.md它不是给模型看的是给人看的。里面写了每类模板背后的设计意图、默认行为和扩展方式。这样团队里有人想改模板至少先理解为什么这样设计而不是自作主张乱改。6. 容易踩的坑与几个值得长期坚持的习惯6.1 上下文溢出是最常见的头号杀手我见过不少把 CLAUDE.md 写成长篇小说的人。项目里所有历史决策、所有代码规范、所有模块说明全塞一个文件结果就是每次对话启动光读这个文件就要占掉几千词的上下文真正干活的空间被挤没了。解决办法前面已经说了记忆文件只放高频必需项长文细节放到按需加载的模板或独立备忘里。如果你发现每次对话都得用某段长指令那就把它做成斜杠命令。如果你发现某个知识只在极少数任务里用到那就根本别放进模板库放在普通文档里需要时让模型去读就完了。6.2 过度规范会让模型变得“死板”这个坑跟上下文溢出恰好相反但同样危险。模板写得太刚、约束条件太多模型会在无关紧要的地方反复跟你确认或者干脆一件事都不干先列二十个问题问你。这种体验也很糟。经验是约束要加在跟任务成败强相关的环节上比如“不修改公共 API”“必须先读取日志再下结论”这类必须硬性约束而细枝末节比如“请使用四个空格缩进”“报告里不要用感叹号”嘱咐一句就够了别把它升级为强制条款。否则你会得到一个看起来严谨、实际上毫无效率的机械式执行者。6.3 全局模板和项目模板互相冲突时的取舍当你同时存在用户级记忆、项目级记忆和命令级模板时冲突几乎不可避免。最典型的场景是用户全局模板里说“所有代码必须用 TypeScript 编写”结果项目里是个纯 Python 服务。这种冲突会直接污染模型的判断。我的规则是一致性优先越具体的越优先。项目级内容高于用户级命令级参数高于记忆文件。如果冲突发生应该在模板开头用一行说明来显式声明优先级不要让模型自己去猜。6.4 不要在模板里放密钥和私有信息安全这个问题值得单独提醒一下。因为模板文件通常是要提交到仓库里的如果你在模板里写了硬编码的 token、密钥、内网地址那这些信息会随着仓库被分发到所有拉取代码的人手里。我的模板库从第一天开始就设置了一条规矩任何模板里出现的具体敏感信息一律用占位符代替实际值通过环境变量或者运行时的上下文补充。6.5 定期给模板“注入新鲜任务”最后说一个长期习惯。模板库最怕的不是没人用而是变成一潭死水。如果一个模板连续三个月没有因为新任务而调整过它大概率已经和真实的项目形态脱节了。我给自己设定的习惯是两周一迭代每两周至少重跑一次最高频的三个模板并用新任务去挑战它们。新任务里往往会出现旧模板覆盖不到的边界这些边界就是模板进化的方向。这套方法走下来claude-code-templates 从一个简单的提示词收藏夹慢慢变成了一套真正能影响日常工作流的基础设施。我不敢说它是完美方案但至少方向是明确的让 AI 编码助手从“你问它答”走向“按约定执行”靠的不是更长的提示词而是更工程化的模板设计。