大概从去年开始,我把日常的编码工作越来越多地交给了Claude Code。用得越久,越发现一个问题:每次新建会话时,花在重新介绍项目上的时间,往往比真正写代码的时间还长。项目背景要重新说,技术栈要重新列,代码规范要重新讲,甚至连不许动哪些文件这种基本约束都要重新交代一遍。最开始我以为是模型理解能力的问题,后来才意识到,问题出在我自己身上——我没有一套属于自己的 claude-code-templates。想通这件事之后,我花了一个周末,把零散写在记事本里的提示词、草稿箱里的指令片段全部整理成了结构化的模板库。现在回头看,这个动作对效率的提升,比我换任何IDE插件都来得明显。这篇文章就把我这套模板库的设计思路、目录结构、实操配置以及踩过的坑全部摊开讲,希望能给同样被重复上下文折磨的人一点参考。1. 为什么需要给自己的Claude Code配一套模板库先说一个可能有点反直觉的观点:模板库表面上是在给AI写提示词,本质上是在给自己写操作手册。Claude Code 这类工具最大的特点是读过什么才知道什么,它本身不保留上一次对话的记忆。你今天跟它说了项目里的模块划分,明天新开会话它照样不知道。这就像你雇了一个能力很强的实习生,但这位实习生每天上班都会失忆,你得把岗位职责重新讲一遍。模板库解决的就是这个失忆问题。把那些每次都要重复的背景信息、规则约束、输出要求固定成文档,让AI在开工之前自动加载,等于把口头交代变成了入职手册。1.1 从一次低效对话说起我印象最深的一次翻车,是在一个 Spring Boot Vue 的遗留项目里让它改登录接口的bug。当时项目里代码风格相当混乱,有老程序员写的匈牙利命名法,也有后来新人也跟着用了驼峰,还有几处明显是粘贴来的第三方示例代码。我在提示词里只写了修复登录接口的NPE问题,结果它不光改了Controller层,还把Service层的命名顺手规范化了,甚至在我没要求的情况下给方法加了密密麻麻的注释。单看它做的事,每一条单拎出来都算合理。但合在一起,那次PR的diff大得离谱,我光review就花了两个小时,最后不得不git checkout了一大半文件的修改。事后复盘,根因很简单:它不知道这个项目的边界在哪,不知道哪些代码是不能动的禁区,也不知道项目本身的风格约定。这些信息我脑子里有,但没告诉它。而模板库,正好就是把我脑子里有但没说出来的东西,变成它一开工就能读到的东西。1.2 模板库的三层真实价值我用了这段时间之后,总结出三层价值,按重要程度排序:稳定性:同一个任务,今天执行和下周执行,结果不会差太远。没有模板的时候,AI的表现完全看它当时的心情——其实就是看你对上下文描述得够不够清楚。有了固定模板,每次的输入基线一致,输出质量自然稳定。效率:这是最直观的收益。以前开一个新项目会话,光写背景说明就要七八行,现在直接/init或者让它读取CLAUDE.md,十秒钟进入工作状态。那种话还没说利索就开始干活的感觉,用惯了真的回不去。沉淀:个人经验、团队约定、项目黑话,这些原本散落在各个人的脑子里。模板库把它们变成可以复制、可以版本管理、可以交接的资产。换人、换机器、加新成员,把模板一同步,老成员脑子里的东西新人也能用。2. 我的模板库由这四类构成网上能搜到很多现成的Claude Code模板仓库,但我建议别直接抄。别人的模板是为别人的项目、别人的工作流服务的,直接拿来用,大概率会出现规则互相打架或者约束完全不适配的情况。我自己的模板库是按用途分成了四类,每一类解决一个层面的问题。2.1 项目级记忆模板让AI入职前先读一遍员工手册这一类模板对应的是项目根目录下的CLAUDE.md文件。它的定位是项目级长期记忆,每次会话启动时,Claude Code 会自动加载,不需要你手动引用。我习惯把它写成一个结构化的员工手册,而不是流水账。一个典型的CLAUDE.md长这样:# 项目概览 - 项目名称: order-center - 技术栈: Java 17 / Spring Boot 3.x / MySQL 8 / Redis - 模块划分: gateway(网关)、order(订单)、user(用户)、common(公共组件) # 常用命令 - 本地启动: ./mvnw spring-boot:run -pl order - 运行全部单测: ./mvnw test - 代码格式化: ./mvnw spotless:apply # 架构约定 - 所有对外接口统一返回 ResultT 包装,禁止直接返回裸对象 - 异常处理统一使用 GlobalExceptionHandler,禁止在业务代码里 try-catch 后吞掉异常 - 数据库访问使用 MyBatis-Plus,禁止手写 JDBC # 禁止事项(非常重要) - 禁止修改 common 模块的公共类,除非任务明确要求 - 禁止升级 Spring Boot 版本 - 禁止改动数据库表结构,涉及表结构变更必须先输出 ALTER 语句供人工确认 # 代码风格 - 命名规范: 类名 PascalCase,方法名 camelCase,常量 UPPER_SNAKE - 注释要求: 只对复杂业务逻辑写注释,禁止给简单 getter/setter 加注释写这些内容的时候有一个关键点:不要写应该怎么做,要写必须怎么做和禁止怎么做。AI 对肯定句的执行力远不如对否定句和边界词敏感。比如接口要返回统一包装这种话,它可能觉得加个ResponseBody就算完成了;但写上禁止返回裸对象,它就会在动手之前多确认一遍。2.2 任务级执行模板把高频任务变成固定流程第二类是任务级的模板,不对应某个具体项目,而是对应一类重复出现的任务场景。这也是我平时用得最频繁的一类,包括代码审查、Bug定位、单元测试生成、依赖升级、日志分析等。以代码审查模板为例,我会在模板里明确写出审查的维度、输出的格式、以及不给建议的场景:请对以下代码变更进行审查。 审查维度: 1. 功能正确性(是否存在边界条件遗漏) 2. 并发安全(是否有多线程共享状态问题) 3. 异常处理(是否有吞异常、catch后无处理的情况) 4. 性能隐患(是否有明显的N1查询、重复循环、大对象持有) 5. 代码规范(是否违反项目中 CLAUDE.md 的命名和结构约定) 输出要求: - 按严重程度从高到低列出问题 - 每个问题标注: 文件路径、行号、问题描述、修改建议 - 如果某维度没有问题,明确写无,不要啰嗦解释 - 不要输出整体代码质量良好这类空话 - 不要主动修改代码,只输出审查意见这类模板的关键在于输出格式约束。AI 默认倾向于友好地跟你说一堆话,但代码审查这种场景,我需要的是结构化的、能直接贴进评论区的结论。把输出格式写死,比在对话里反复纠正它要有效得多。2.3 角色与边界模板用 Subagents 隔离职责第三类是角色模板,对应的是.claude/agents/目录下的子代理(Subagent)定义。简单说,就是让不同的Agent承担不同职责,互相隔离,避免一个Agent什么都干导致的上下文污染。我目前维护了三个子代理:reviewer:专职代码审查,只看不改,输出审查报告。debugger:专职问题排查,可以读日志、检索代码、做实验,但不允许直接修改业务代码。refactor-tool:专职重构,只允许在测试覆盖的范围内动代码,禁止顺手修无关问题。一个典型的子代理定义文件长这样:--- name: debugger description: 用于定位 bug 的辅助代理,擅长从日志和堆栈中分析根因 --- 你是一个专注的问题排查专家。你只负责定位问题,不负责修复。 你可以: - 读取项目日志、堆栈信息 - 检索相关代码文件和调用链 - 提出你的假设并让用户验证 你禁止: - 直接修改业务代码 - 顺手优化无关代码 - 在没有完整调用链证据的情况下下结论 当用户要求你修复问题时,请明确拒绝,并输出你的排查结论和修复建议,等待用户确认后由主会话执行。有人可能会问:直接在主会话里要求它扮演不同角色不就行了吗? 理论上可以,但实际效果差很远。主会话的上下文是累积的,聊了半小时需求之后,再让它切换到严格审查模式,它很容易把前面闲聊的内容也带进判断。子代理相当于开了一个独立的上下文窗口,干净、专注、不会串味。2.4 输出格式模板让结果可直接被程序消费第四类是输出格式模板,专门应对结果要喂给别的工具的场景。比如:生成 Git 提交信息时,要求输出符合 Conventional Commits 规范的单行文本。生成接口文档时,要求输出 OpenAPI 3.0 的 YAML。生成测试用例时,要求输出可直接执行的 JUnit 代码,且不带讲解。这类模板内容非常短,但极其有效。核心思路是:能结构化,就别让人再转发一道。举个实际例子,我让它生成数据库迁移脚本时,模板里会写:只输出一个 SQL 文件内容,文件内包含完整的-- goose Up和-- goose Down注释块,不要附加任何解释性文字。 这样生成的脚本可以直接落盘执行,不需要我再手动去除Markdown代码块标记。3. 把模板从复制粘贴变成一键触发模板写在文档里,终究需要手动复制粘贴。用久了你会发现,这一步虽然只要几秒钟,但对心流的打断是实打实的。所以我把模板进一步封装成了 Slash 命令,让高频操作变成斜杠命令名一键触发。3.1 用 .claude/commands 目录注册自定义命令Claude Code 支持在项目的.claude/commands/目录下放一批 Markdown 文件,文件名就是命令名。比如我建一个review.md,文件内容就是上面2.2节那段审查模板,那么在会话里输入/review就能直接加载这段指令,后面再加具体参数。我的做法是这样的目录结构:.claude/ ├── commands/ │ ├── review.md # 审查代码 │ ├── debug.md # 定位 bug │ ├── test.md # 生成单测 │ ├── changelog.md # 生成提交信息/更新日志 │ ├── migrate.md # 生成数据库迁移脚本 │ └── explain.md # 解释一段代码 └── agents/ ├── reviewer.md ├── debugger.md └── refactor-tool.md每个命令文件的开头部分,我会写上简短的元信息:--- description: 审查当前分支的代码变更,按严重程度输出问题列表 ---这个description字段不是摆设。当你不确定用什么命令时,直接输入/会弹出命令列表,列表里显示的就是这段描述。写清楚描述,等于给自己做了一个命令速查表。3.2 参数传递让模板从死板变灵活如果模板只是固定的一堆文字,那它还谈不上好用。真正让它活起来的是参数传递。Claude Code 的自定义命令支持通过$ARGUMENTS引用用户输入,例如:请审查以下代码变更: $ARGUMENTS 审查维度: ...我在会话里输入/review 修复了登录接口的NPE,模板就会自动把修复了登录接口的NPE这几个字插入到$ARGUMENTS的位置,后面的审查维度、输出格式照常生效。这个设计带来的好处是:模板本身是稳定的,模板接收的内容是灵活的。稳定的部分保证输出质量,灵活的部分保证适配具体场景。3.3 把高频系列操作编排成命令组合单条命令只能做单件事。实际工作流里,很多任务是一系列动作的组合。比如改完一个 bug,要跑测试、更新 CHANGELOG、生成提交信息,这个流程我通常手动分三步执行,但后来发现,Claude Code 一个会话里可以连续调用多条/命令,那就干脆把目标写清楚,让它自己按顺序调用。我目前比较满意的组合命令是fix-and-commit,它的模板是这样的:请完成以下修复任务: 1. 定位 $ARGUMENTS 描述的 bug 根因 2. 修复问题,但严格遵循 CLAUDE.md 中的所有禁止事项 3. 运行相关模块的单元测试,确保没有回归 4. 按 Conventional Commits 规范生成提交信息,并提交到当前分支 在执行第2步之前,先输出你的修复方案和涉及文件列表,等待我确认后再动手。注意第4条带了一个先确认再动手的步骤。这个设计是因为,AI 在给定目标之后往往会过度热情地一路做下去,中间停下来问一次要不要继续,可以避免很多不必要的返工。如果你用的是支持 Skills 的新版本,还可以把任务模板写进.claude/skills/目录,每个 Skill 包含一个SKILL.md,里面写清楚该技能的触发条件、执行步骤和输出约定。命令加技能的组合,基本能把 90% 的重复劳动变成一句话的事。4. 模板库的组织方式与命名规范模板数量一多,如果没有一套清晰的组织规则,库就会变成第二个乱七八糟的记事本。我在整理的过程中踩过不少坑,最后沉淀下来一套还算好用的规范。4.1 我的完整目录结构我现在同时管理两套模板:一套是个人全局模板,放在用户目录下,作用于所有项目;另一套是项目本地模板,随项目走,作用域只限当前代码库。~/.claude/ ├── CLAUDE.md # 全局记忆,所有项目可见 ├── commands/ # 全局命令 │ ├── review.md │ ├── debug.md │ └── ... └── agents/ # 全局子代理 ├── reviewer.md └── ... 项目根目录/ ├── CLAUDE.md # 项目记忆,只对当前项目生效 └── .claude/ ├── commands/ # 项目专属命令 │ ├── build.md │ ├── deploy.md │ └── ... ├── agents/ # 项目专属子代理 └── skills/ # 项目专属技能这个全局 项目的两级设计,解决了一个核心问题:通用能力和特殊约束的分离。全局模板里放的是所有代码项目都适用的规则,比如提交信息要符合 Conventional Commits生成代码必须附带单元测试这类。项目模板里放的是只有这个项目才适用的约束,比如这个项目的模块边界、禁止事项、特有命令。打个比方,全局模板是职场基本礼仪,项目模板是你所在部门的规定。两者分开维护,才不会出现改A项目的约束结果影响了B项目的连锁事故。4.2 命名规范动词开头加场景限定词命令命名如果太随意,用不了几天自己都会忘。我现在的命名规范是:一律用动词开头,后面跟着场景限定词。好的命令名:/review—— 审查代码/fix-bug—— 定位并修复bug/gen-test—— 生成单元测试/write-migration—— 生成数据库迁移脚本不太好的命令名:/code—— 太宽泛,AI不知道你要干嘛/check—— 检查什么?语法?依赖?安全性?/help—— 这是拿命令名当聊天了如果你发现一个命令名需要超过三个单词才能说清楚,那就说明这个命令的职责切得还不够细,应该再拆一拆。比如/fix-bug-and-write-test-and-update-doc这种,拆成/fix-bug加一个后续的/gen-test,逻辑会清晰得多。4.3 模板文件的大小红线模板不是越详细越好。我踩过一个典型坑:一开始觉得反正模板是给AI看的,写得越细它理解越准,结果把一个CLAUDE.md写到了两百多行。实际用下来,效果反而变差了。原因也很简单:上下文窗口是有限的,当CLAUDE.md里的规则多到一定程度,AI 在执行具体任务时会把注意力分散到各种边角规则上,甚至出现过度遵守某条规则导致另一条更重要的规则被忽略的情况。我到后面甚至遇到过它为了符合禁止直接返回裸对象这条规则,在工具类里硬造包装类的搞笑行为。现在我给自己定了一条硬性红线:单个模板文件控制在60行以内,CLAUDE.md控制在80行以内。如果内容超过这个量,就说明该拆分了——把通用的拆到全局模板,把任务特定的拆到命令文件,把纯技术细节拆到独立文档里用链接引用。5. 用 Git 管理模板版本化、同步与团队分享模板的价值会随着时间累积,但如果它只躺在你的一台机器里,那价值就要打很大折扣。我自己的模板库已经是第三版了,前两版都因为没有版本管理而翻车——改着改着发现某个命令不好使了,但怎么也想不起来改前是什么样的。5.1 为什么模板也需要版本管理模板本质上是代码,只不过它是给AI看的代码。它会演化,会有我试了个新写法发现不行,想退回旧版的需求。用 Git 管理之后,我可以随时比较两个版本之间命令定义的变化,也能给每轮较大的调整打上 tag。更实际的一个好处是:有了 Git,改模板的心理负担会小很多。以前改一个命令文件,总担心改坏了找不回原样,现在大不了git revert。这个心理变化带来的直接收益是,我试错的频率高了很多,模板迭代速度快了一倍不止。5.2 跨设备同步的实操方案我在家里和公司各有一台主力机器,以前用网盘同步文件夹,经常出现这台改了那边没同步的冲突。后来我改用 Git 仓库统一管理全局模板,操作流程很简单:# 在全局模板目录初始化仓库 cd ~/.claude git init # 关联远程仓库(私有仓库) git remote add origin gitgithub.com:yourname/claude-templates.git # 日常改动提交 git add -A git commit -m refactor: 拆分 review 命令,新增输出格式约束 git push origin main # 在另一台机器拉取 git pull origin main项目级模板我一般不放个人远程仓库,而是直接提交到项目自己的代码库里。这样团队成员git clone项目时,模板库就自动跟着下来了,新人上手成本骤降。5.3 给团队共用时,哪些规则一定要写进去如果你打算把模板库分享给团队,有几个细节必须提前想清楚:敏感信息拦截:模板库里严禁出现任何明文密钥、内网地址、数据库连接串。AI 读完模板后是有可能把内容原样输出到对话里的,这个风险不能赌。项目约定要写成团队共识而非个人偏好:比如注释要写中文还是英文是否允许使用Lombok这种问题,如果团队本身没有统一,千万别自己拍脑袋写进模板,否则AI会严格执行你的偏好,引发队友不满。禁止事项要做减法:团队模板里的禁止条款,应该是所有人公认的雷区,而不是你个人的洁癖。每加一条禁止,都意味着将来有不小的概率误伤,所以务必克制。6. 模板库从好用到翻车的四个经典坑最后这部分,我把自己真实踩过的坑整理出来。有些坑在踩之前,我甚至没意识到它是个坑。6.1 规则堆砌导致 AI 畏首畏尾第一条也是最隐蔽的一条。当你把禁止规则写到一定密度之后,AI 会开始变得极其保守。它会倾向于什么都不做,先问你一遍,因为对所有操作都心存疑虑。表现就是:以前给个任务它直接开干,现在每一步都要跟你确认这一步是否可以执行。表面上看起来是更谨慎了,实际上效率直接腰斩。我的解决方案很简单:把禁止类的规则集中放一块,并且在模板末尾加一句对于未在禁止列表中的操作,默认允许,无需额外确认。这句话极大地缓解了过度谨慎的问题,因为AI不再需要为没被禁止的每个动作担忧。6.2 过时的模板假设让AI在错误的路上狂奔模板里的过时信息比没有信息更危险。举个例子,我在某个项目的CLAUDE.md里写了一句数据库默认使用 H2 内存库,连接串见 application-dev.yml。后来项目推进,数据库换成了 PostgreSQL,YAML 配置全部重构了。但我没有同步更新模板。某次让AI排查一个连接超时问题,它拿着过时的模板,对着不存在的H2配置分析了大半天,还理直气壮地输出了一堆错误结论。问题完全出在模板没有跟随项目演化。从那以后,我给自己加了一个规矩:每次项目发生架构级变动,第一件事就是更新CLAUDE.md。这应该是一个强制动作,而不是想起来才做的可选动作。6.3 全局模板覆盖局部规则的冲突这个坑出现在我引入全局 项目两级模板之后。全局模板里有一条所有代码必须有单元测试,但某个内部工具项目其实根本不跑测试,这条规则每次都会触发AI额外编制无意义的测试骨架。调优的过程让我理解了一件事:全局模板只能放绝对不会错的规则,凡是有可能不适用的规则,一律下放到项目级。判断方法也很简单,在写一条规则时问自己:如果全世界所有项目都执行这条规则,会不会有任何一个项目觉得莫名其妙?只要有一个,这条规则就不配待在全局模板里。6.4 缺了验证闭环,模板的正确性无从谈起最后一个坑是关于维护的。以前我写完一个命令模板,试一次能用,就不再管了。直到某次升级了 CLI 工具之后,好几个命令的description字段解析出了问题,我才意识到模板也是有兼容性的。现在我对每个新增或修改的模板,都会做一次标准化验证,流程固定为:找个最小的测试项目,执行该命令,确认能被正确加载。故意传入一个异常输入,确认AI不会因为模板里有输出格式要求就忽略异常输入的真实性。检查模板里是否有项目特定的假设,如果有,移到项目级目录。提交 Git,写清楚这一次变更解决了什么问题。这套流程走下来,单个模板平均多花五分钟,但换来的是一年到头不会再遇到命令突然不生效的尴尬。最后再分享一个我个人很受益的小技巧:模板库里最适合优先构建的,不是那些看起来很厉害的复杂工作流,而是你每周至少会重复三次的琐碎操作。哪怕它只是给这段代码补上标准化的Javadoc注释,只要频率够高,就值得沉淀成模板。模板带来的收益是复利性质的,你每次用它的时间,都是在为之前那次设计工作收利息。
