1. 为什么要为Claude Code建立模板从裸奔到资产沉淀1.1 临场发挥的成本被低估了用过Claude Code的人多半有过这种体验明明是同一个项目每次开新会话都得把技术栈、目录结构、编码规范从头再说一遍甚至对话到一半AI就忘记了上下文。一开始我以为是自己不会提问直到我把注意力放到 claude-code-templates 这个方向才意识到问题出在每次从零开始而不是工具本身。我见过不少团队和个人开发者工具装得很勤快使用方式却一直停留在打开对话框想到什么问什么。这种用法不是不行但代价是每开一个会话就要重新交代一遍背景。今天让AI改个接口它不知道你项目里用了pnpm而不是npm明天让它写个测试它不知道你们的单测框架是Vitest而不是Jest。你一旦忘记说这些AI给出的方案大概率是通用但不符合你项目的你还得花时间纠正。说得直白一点这是把AI当成一个记忆力只有几十分钟的实习生每次都要重新培训。培训成本由谁承担还不是你自己。我最初也以为这是工具的限制直到整理出一套 claude-code-templates才把临场发挥变成了按模板开工。1.2 模板的本质是把好状态固定下来那这套模板到底存了什么不只是几条提示词我把它分成三层层级承载内容典型载体解决的问题交互指令层角色、任务、输出格式要求角色模板、任务模板回答风格不稳定、目标不明确项目知识层技术栈、目录约定、命令CLAUDE.md、上下文模板AI不熟悉项目、瞎猜技术方案工作流层重复性操作封装命令别名、模板组合每次重复输入、操作不统一打个比方这就像厨师炒菜。没有菜谱的厨师状态好时做得好吃状态差时发挥不稳定有了菜谱哪怕换了个厨房只要按步骤来出品就能保持在合格线以上。模板就是把那些靠运气才能保住的发挥变成稳定可复用的东西。在着手搭建模板库之前我还建议大家想清楚一个问题你希望AI在什么场景、以什么身份、按什么流程帮你干活。这决定了你的模板是提示词收藏夹还是一套真正能运转的协作系统。收藏夹是散的系统是合的。1.3 这套模板库的整体结构我维护的这套模板目录结构大致是下面这样claude-code-templates/ ├── roles/ # 角色模板 │ ├── senior-reviewer.md │ ├── refactoring-engineer.md │ └── debug-expert.md ├── tasks/ # 任务模板 │ ├── implement-feature.md │ ├── write-tests.md │ └── fix-bug.md ├── context/ # 上下文模板 │ ├── tech-stack.md │ └── repo-map.md ├── CLAUDE.md # 项目级总入口 └── README.md # 模板库使用说明为什么要按目录拆而不是把所有模板堆在一个文件里原因很简单不同任务需要的上下文量不一样。代码评审需要的是一套标准写新功能又是另一套标准如果全放在一起AI每次都要加载大量无关指令既浪费上下文空间也容易让关键约束被稀释。拆开来按需组合是模板库能不能真正好用的关键。2. 模板集的骨架拆解角色、任务、上下文三件套2.1 角色模板给AI一张身份卡角色模板是大家最容易理解、也最容易做错的一类。很多人写的角色设定是你是一位经验丰富的工程师然后没了。这种设定有效果但效果有限因为它没有给AI足够的边界和操作规则。我推荐的写法是身份、职责、输出格式、约束四条都要有。这样AI才知道自己该关注什么、不该做什么、用什么格式汇报。下面是我在角色模板里很常用的一个示例用于代码评审你是本项目的高级后端代码评审人。 你的职责 - 审查代码的正确性、可维护性、性能和安全 - 优先关注数据流、错误处理、边界条件 - 对每个发现的问题标注严重程度P0 / P1 / P2 你的输出格式 - 先给总结性问题清单按严重程度排序 - 每个问题包含文件位置、原因分析、具体修改建议 - 如果没有问题直接说未发现明显问题不要长篇大论 约束 - 不要直接修改代码 - 不要提出与项目技术栈不一致的建议 - 不确定的结论要标注推测不能当成事实注意最后那条约束不确定的要标注推测。这一条在实际使用中价值很高。AI很容易把概率性的判断说成确定性的结论加了这个约束之后它的输出会谨慎很多。这是我在实际用的时候反复测试后加进去的因为它能救回不少因为AI自信满满地给错误答案而浪费的时间。2.2 任务模板把目标讲清楚而不是靠猜角色模板定义的是你是谁任务模板定义的是你要做什么。两者经常一起用但团队协作里最好各自独立成文件方便按场景自由组合。一个合格的任务模板至少要包含四个部分目标背景、输入材料、输出产物、验收标准。背景信息给AI一个判断基础输入材料告诉它从哪里开始输出产物决定它的回答形态验收标准则是你用来判断它是否做对事情的标尺。以一个修Bug的任务模板为例任务修复登录接口在并发请求下偶发返回 500 的问题 背景登录接口在并发请求下偶发返回 500 疑似 session 竞争条件导致。入口文件为 src/auth/login.go。 处理步骤 1. 先定位根因不要直接给补丁 2. 输出一份根因分析报告再给出修复代码 3. 修复后补充一个并发回归测试 4. 说明你的修复为什么不影响现有逻辑 验收标准 - 复现步骤跑通500 不再出现 - 相关测试全部通过 - 改动文件数量尽量少这种写法之所以有效是因为它把怎么算做完定义清楚了。很多时候AI给了方案你以为它做完了结果发现少写测试、或者改掉了无关代码。验收标准就是用来堵住这个漏子的。2.3 上下文模板给AI喂项目体检报告上下文模板是被忽视最多、但收益往往最大的部分。打个比方你让一个工程师去看一个新仓库的代码他第一件事肯定是看README、看依赖配置、看目录结构。AI也一样如果你不在上下文里喂给它这些信息它就只能用通用知识来猜而通用知识通常绕不过你项目的特殊约定。一份比较完整的项目上下文模板至少应该包含下面这些信息# 技术栈 - 语言: TypeScript 5.x - 框架: Next.js 14App Router - 数据库: PostgreSQL 16 - ORM: Prisma - 包管理器: pnpm # 常用命令 - 启动 dev: pnpm dev - 跑测试: pnpm test - 类型检查: pnpm tsc --noEmit - lint: pnpm lint # 目录约定 - src/app: 路由与页面 - src/components: 通用组件 - src/lib: 服务端工具与公共逻辑 # 项目特殊约定 - 组件默认使用 Server Component需要交互再加 use client - 错误信息统一用 i18n key不用硬编码别小看这份体检报告。我试过在一个中型项目里把这份内容首次喂给AI后它给出的方案命中率明显上升。原因也不复杂AI在回答问题前就有了正确的上下文不用靠猜。上下文模板和CLAUDE.md的关系后面会专门讲。简单说CLAUDE.md适合放那些每次会话都需要的稳定信息上下文模板适合放那些特定场景才需要、但内容量又比较大的信息用到时再加载。2.4 模板的组合逻辑拆成三件套之后实际使用时不是一次用单一模板而是组合使用。我最常用的组合方式是先加载上下文模板再给角色模板最后给任务模板。顺序基本上是粘贴 context/tech-stack.md 接下来请你扮演高级后端评审人角色模板已加载。 任务审查 src/auth/login.go 的并发安全性任务模板已加载。 请按模板要求输出问题清单。为什么要按这个顺序因为上下文相当于给AI建立了一个正确的世界模型角色模板给它划定关注范围和表达方式任务模板则给出具体目标和验收标准。顺序一旦乱了比如先给任务再给上下文AI可能会先基于错误假设开始推理后面的上下文反而像是在打补丁。这里面的逻辑用过几次你就能体会出来。3. 让模板真正跑起来CLAUDE.md、配置与命令别名3.1 CLAUDE.md是模板库的总入口如果你只是把模板放在文件夹里每次要用的时候才复制粘贴那模板库的利用率会很低。真正让模板跑起来的关键是让Claude Code在启动时自动加载项目约定。在这个环节CLAUDE.md是核心。我理解的机制是Claude Code 在读取项目时会识别仓库根目录下的 CLAUDE.md 文件将其内容作为项目级指令自动注入会话上下文。这意味着你不需要每次手动粘贴那些稳定不变的项目约定AI在进项目的时候就已经知道了。所以我在模板库的CLAUDE.md里会放三类内容# CLAUDE.md ## 项目简介 一句话尽可能短主要说明这个项目是什么、给谁用。 ## 技术栈与命令 - 见 context/tech-stack.md维护标准命令与依赖信息 ## 开发工作流约定 - 先看 issue 描述再动代码 - 提交信息遵循 conventional commits - 改动前先跑一次相关测试 ## 常用模板入口 - /review - 代码评审角色模板 - /fix - 修 bug 任务模板 - /feature - 新功能开发任务模板注意我的CLAUDE.md本身写得比较短详细的技术栈放在context模板里。原因是CLAUDE.md每次会话都会加载写得越长Token占用越大。与其把一次性的长篇背景塞进去不如让CLAUDE.md做索引把详细内容拆到按需加载的模板文件里。这里要特别提醒CLAUDE.md的定位是项目记忆不是万能模板库。把所有角色模板都塞进去绝对是错误用法——它会让你每一次对话都背负大量无关指令AI的回答反而会变得泛化。3.2 用配置和命令别名把模板变成按钮模板文件建好了CLAUDE.md的索引也有了下一步是让调用模板变得更顺滑。我最推荐的方式是把高频率模板绑定为命令别名这样在对话里输入一个短命令就能唤起对应的模板内容。具体实现方式根据Claude Code版本会略有差异我这边就不写死配置字段了以你当前版本的官方文档为准。但核心思路是一致的给每个模板定义短名称、说明和映射内容。举例来说我会把代码评审模板绑定为 /review把修Bug模板绑定为 /fix。这样我只需要在输入框里敲 /review模板就会展开或者被AI理解比去文件夹里翻文件再粘贴快得多。另一个思路是把模板做成会话开场白。如果你有多个高频场景可以给每个场景准备一个开场白模板里面包含角色、任务、输出格式的组合调用。我常用的开场白模板长这样本次会话目标目标 涉及目录目录路径 请先读取相关文件总结你的理解再给出执行计划。 注意如果需求与模板冲突先指出冲突不要擅自假设。最后那句如果需求与模板冲突先指出冲突也是我踩过坑之后加的。为什么因为AI在一段长对话里很容易被中途补充的信息带偏有了这句它至少会在偏离前停下来确认而不是自作主张。3.3 不同场景的组合装配顺序模板用顺了之后你会发现大部分工作流都是可以预定义的。我总结过几个高频场景的装配顺序在这里直接给出来方便你参考场景装配顺序典型输出新功能开发上下文模板 角色模板 任务模板技术方案 分步实施计划 代码修Bug上下文模板 任务模板修复类根因分析报告 修复代码 回归测试代码评审上下文模板 角色模板评审人P0/P1/P2 问题清单写测试上下文模板 任务模板测试类测试计划 单测代码 覆盖率说明这些组合看起来简单但它们解决了一个真实问题把跟AI协作时的混乱和随机性降下来了。有了固定的装配顺序你不需要每次重新想该怎么向AI描述背景只需要对照表格选择组合就行。4. 用迭代经验打磨模板踩过的坑和验证方法4.1 模板不是越长越好我最早写角色模板的时候追求全面一口气写了三千多字把各种细枝末节的规则都塞进去。结果发现AI的回答变得又长又正经但关键约束反而经常被忽略。这是典型的信号稀释问题指令越多每一条的权重就越低。后来我把模板压缩到150到300行甚至更短同时把最核心的约束放在开头和结尾。这是利用上下文注意力分布的特点开头的信息容易被记住结尾的信息容易被当作最新要求中间的内容容易被忽略。所以我现在写模板时核心约束要么在最前面要么在最后面中间只放常规步骤。具体压缩方法每一段写完后问自己一句——这段删掉AI会不会乱来如果不会就删。一个模板如果只能留三句话那就留在身份、输出格式、最高优先级约束这三条上。4.2 模板不生效的常见原因模板写好但效果不好的情况我遇到过的原因主要是以下几类第一约束写得太软。像尽量可以考虑最好这类词AI很容易当装饰品忽略。后来我全部改成祈使句不要X除非Y如果A必须先B。软约束和硬约束的执行力差距非常明显。第二多个模板之间存在隐性冲突。比如上下文模板说项目用Vue角色模板里却带着一段React代码示例AI就会无所适从。每次改模板库都应该顺手检查一下不同模板之间有没有互相矛盾的信息。第三模板维护没跟上项目变化。项目技术栈升级了、目录重构了但模板还停留在三个月前。用一份过时的模板比不用模板更危险因为它会让AI自信地给出错误假设。第四用户中途补充的信息冲淡了模板约束。这个问题我没有完全规避掉但现在会在模板末尾加上一句如果需求与模板冲突请先指出冲突不要擅自假设。这句的作用是给AI一个刹车信号偏离模板之前停下来确认一下。4.3 用版本管理和回归测试来维护模板模板维护这件事我是当代码来管理的。具体有三条实践第一把模板目录纳入Git管理。每个模板单独一个文件任何改动都有commit记录。哪天把模板改坏了git checkout就能回到可用状态。第二给模板库维护一个简短的更新日志。不用写得很正式两三行记录这次改了哪个模板、为什么改、期望效果是什么就够了。这个日志到月底回看时很有价值能帮你判断哪些改动是真有效的哪些是瞎折腾。第三准备一套回归验证素材。我平时会在本地准备一个固定的测试项目每次调整模板库之后用同一段任务去跑一遍重点看AI的准确性、约束遵守度、输出格式符合度这三项。如果调整后某项明显退步就回滚。这个办法成本极低但能把我觉得模板变好了变成模板确实变好了。实测下来维护模板库最大的阻力不是技术而是懒。头一个月你会觉得有这时间不如多写两行代码但坚持三个月后你会发现凡是重复性的工作打开模板就是标准操作反而省出了大量时间。5. 从我的模板出发快速搭建属于你的模板库5.1 最小骨架三份文件起步我不建议你上来就照着我的目录建几十个模板文件。模板库里堆一堆从不使用的模板反而会让你找不到重点。最合理的起步方式是三份文件your-project/ ├── .claude/ │ └── context/ │ └── tech-stack.md # 你的项目体检报告 ├── templates/ │ ├── role-reviewer.md # 你最常用的角色模板 │ └── task-implement.md # 你最常用的任务模板 └── CLAUDE.md # 项目记忆总入口这三份文件覆盖了最基础的诉求让AI知道项目情况、知道以什么身份干活、知道按什么步骤交付。用顺手之后再根据实际需要逐步增加新的角色模板或任务模板。5.2 按项目类型挑选模板组合不同项目模板的侧重点差异很大。我服务过几个不同类型的项目体验是Web业务系统最需要项目特殊约定这种上下文模板因为框架约定多、容易踩坑老旧的遗留系统最需要约束类模板因为AI很容易提出改写架构的方案你得明确告诉它不许大改算法类项目则更需要输出格式模板因为实验结果如果不固定格式根本没法比较。我常用的一个思路是把项目里最容易出问题的三件事写进模板的最高优先级约束里。如果你的项目总是因为AI不熟悉构建命令而出错那就把构建命令写进CLAUDE.md如果AI总是过度设计就在角色模板里加一行优先用最简单可用的方案。模板的真正价值不在多而在精准。5.3 建立属于你的模板迭代节奏最后想分享一个让我受益很多的习惯用完AI之后顺手记录一句话。我通常是在每次会话结束后花十秒钟想一下——这次如果模板里多写了某条规则下次是不是会更好然后立刻补进对应的模板文件备注一行修改原因。每周末我会花十分钟统一整理一次把本周收集到的零散改进点合并进正式模板删掉那些当时觉得有用、实际没用的冗长指令。这个节奏说起来很简单但坚持下来你的模板库就会像代码库一样持续演进而不是写一次就放在角落吃灰。我最初以为模板会限制AI的自由发挥用了半年之后反而发现恰恰是有了模板AI不用把注意力浪费在猜项目约定上才有余力把真正的创造力花在疑难问题上。我最后再分享一个小技巧在模板库根目录放一个README把每个模板的适用场景、触发方式、最新修改记录写清楚。等你换一台电脑、换一个团队或者重新打开一个三个月没碰的项目时才会真正发现这份文档值多少钱。