只要你在终端里试过一次 Claude Code大概都经历过同一个阶段前几分钟觉得它神了命令一把梭改 bug 快得离谱但越往后用越觉得飘——换个项目它就好像失忆了一样把之前的约定忘得一干二净同一个错误能犯三遍甚至在不同仓库里给你的代码风格都不一样。我的转折点是在一次紧急重构时彻底爆发的项目里原有的一套代码规范、目录约定、禁用项全靠我每次手敲一大段上下文塞给它稍微漏两句它就放飞自我。那一刻我意识到问题不在模型而在我没有把规则变成模板。后来我专门整理了属于自己的 claude-code-templates也就是一套针对 Claude Code 的可复用提示词、项目记忆和斜杠命令模板库把临时聊天的助手变成开箱即用的稳定队友。这篇博文我就完整分享一下我的模板体系、关键文件怎么组织、每个模板到底写了什么、以及踩出来的哪些坑你别再踩。这篇内容适合已经在用或者准备用 Claude Code 写代码的人不管是刚接触想少走弯路还是用了一段时间觉得不够听话你都能从里面找到可以直接抄走的模板结构和写法。1. 为什么需要一套 Claude Code 模板从零配置到工程化1.1 没模板的时候我每天在干同一件蠢事先说一个最扎心的场景。你新开一个仓库想让它帮你写个模块。第一轮对话你花五分钟把技术栈、目录结构、命名风格、不能用什么库、测试怎么写……全部用自然语言喂进去。它这次表现得不错因为上下文里全是你的要求。但第二天接着干新开一个会话你会发现自己又变回了复读机。更可怕的是如果团队里有三五个同事同时在用每个人喂的规则还不一样等于同一个项目在不同会话里拥有完全不同的人格。这是我在实际项目里最真实的痛点没有模板的 Claude Code 是个金鱼脑每次重启都像新认识一个同事。我试过把规则写进普通文档让 AI 去读效果一般因为它不知道该什么时候去读、读多深。我也试过把超长规则全部塞进 system prompt,但很快发现上下文被吃干净它能记住项目代码的地方反而少了。后来我才琢磨明白Claude Code 本身给了两个非常核心的扩展点一个是自动加载的项目记忆文件 CLAUDE.md一个是可以自定义的斜杠命令这些才是模板真正应该落脚的载体。1.2 模板库到底在解决哪几类问题把问题分类之后目标就清楚多了。我总结下来模板库至少要覆盖四个维度第一项目身份记忆。让每一个会话打开时不需要用户复述就知道这个项目是什么技术栈、目录怎么排、代码风格是什么、有哪些禁忌。第二高频动作固化。把帮我 review 这次改动写测试重构这个函数这类重复度极高的动作变成一个斜杠命令一次敲入稳定输出。第三角色与人格切换。同一个对话里你可能一会儿要它当严格的安全审计员一会儿要它当追求速度的算法原型工。模板把人格也做成可插拔的。第四场景模板沉淀。新项目进来从零搭建一套规则太慢直接用技术栈模板初始化五分钟就能让 AI 对这个新项目了如指掌。1.3 一份好模板的评判标准我见过不少人的模板其实就是堆了一大段华丽词藻的 prompt看着很酷用起来很感动实际没用。我的评判标准很简单第一模板是结构化的不能是一堵密不透风的墙。它应该像代码一样有段落、有层级、有关键字AI 读取时能快速检索到最相关的内容。第二模板是模块化的彼此之间能组合。一个项目模板里可以引用通用的代码风格模板一个角色模板里可以引用工具调用约定而不是每个模板都重复造轮子。第三模板是可维护的改一处能全局生效。如果改了命名规范所有涉及的文件都能响应而不是要手动改十个 prompt。这三点想清楚了整个模板库就不再是散装提示词而是一套有工程结构的配置系统。接下来我把我现在的具体结构摊开给你们看。2. 模板库的核心模块拆解CLAUDE.md、斜杠命令与角色预设2.1 CLAUDE.md 项目记忆模板把上下文固化下来Claude Code 有个机制在项目根目录放一个 CLAUDE.md每次启动会话时它会自动读取相当于给 AI 的入职手册。这个文件是模板体系的地基我所有项目的差异都从这里开始。先看一个我常用的基础版结构# CLAUDE.md ## 项目概览 - 项目名: xxx-service - 技术栈: TypeScript NestJS PostgreSQL Redis - 一句话定位: 面向 xxx 场景的异步任务处理服务 ## 目录结构规范 - src/modules: 业务模块按领域划分 - src/common: 通用工具、装饰器、过滤器 - src/config: 配置项禁止在业务代码中直接读取 process.env - tests: 单元测试与 src 镜像对应 ## 代码风格要求 - 使用严格模式 TypeScript禁止 any - 函数命名使用动词开头组件命名使用 PascalCase - 所有对外接口的 DTO 必须手写校验规则禁止信任外部输入 - 错误处理统一使用 AppException禁止直接 throw new Error ## 测试要求 - 核心业务逻辑必须有单元测试覆盖率阈值 80% - 测试命令: npm run test - 禁止用 mock 整个数据库驱动必须用真实容器跑集成测试 ## 明确的禁忌 - 禁止引入 lodash整套工具函数我们自己维护 - 禁止在事务外部执行写操作后不及时提交 - 非必要不新增第三方依赖新依赖必须在 README 中登记写的时候有个小技巧不要只写要什么还要写为什么。比如禁止 any这件事AI 知道规则但规则多的时候它会权衡如果你补一句因为历史遗留的 any 已经导致三次线上运行时错误它在权衡时就会更坚定。CLAUDE.md 不是越长越好。我有次把整个团队的 wiki 全塞进去结果模型处理重要任务时还在想着 wiki 里的边角料规则响应质量反而下降。现在我的原则是只放 AI 做日常任务时必须在场的规则边缘情况放到后面要讲的文档索引里。2.2 Slash Commands 模板把高频动作变成一条指令CLAUDE.md 解决它知道规则斜杠命令解决它知道你要干什么。Claude Code 支持在项目里创建自定义斜杠命令文件放在.claude/commands目录下一个命令对应一个 markdown 文件。我定义命令的核心思路是把自然语言长对话压缩成一道标准工序。比如团队每天都要做代码 review如果直接告诉 AI帮我 review 一下这次改动它可能只挑几个刺草草了事。但我会写一个专门的 review 命令把关注点、输出格式、禁止事项全部固定住。一个完整的命令模板大概长这样# 文件: .claude/commands/review.md 你是本项目的高级代码审查员。请基于项目 CLAUDE.md 中定义的规范对以下改动进行严格审查。 ## 审查范围 用户提供的 $ARGUMENTS 指向的 diff 或文件路径默认审查当前工作区未提交的改动。 ## 必须检查的点 1. 是否违反 CLAUDE.md 中的代码风格与命名规范 2. 是否存在明显的并发问题、事务问题、资源未释放 3. 错误处理是否遵循项目统一模式 4. 是否引用了项目禁止的依赖或写法 5. 新增代码是否有对应测试 ## 输出格式 - 先说结论: PASS / FAIL / WARN - 按严重级别列出问题每个问题标注文件路径与行号 - 最后给出修改建议建议要具体到可以直接执行的代码片段 ## 禁止行为 - 禁止泛泛而谈必须引用具体代码 - 如果改动较小禁止为了凑数编造问题你看它把AI 的自由散漫锁死在一条严格的流水线里。这个文件本身就是模板库最核心的单位。2.3 角色与工作流模板针对不同任务切换人格Slash 命令适合动作型任务但还有一些任务是角色型的——你需要 AI 沉浸式地扮演某种思维角色而不是执行一个独立动作。这时候我会用角色模板。比如我有一个security-auditor角色模板它不是让 AI 检查一下代码而是要求它整个会话里都以攻击者的视角去审视全部代码包括读配置、扫依赖、追线索。还有一个junior-mentor角色适合在代码讲解场景使用它会刻意用类比讲清楚概念避免直接甩一堆术语。角色模板的写法跟命令模板不太一样它更强调认知框架而不是流程步骤。我的经验是角色模板至少要有性格基调、知识边界、表达方式、工作习惯这四段缺了任何一个角色都会塌成普通模式。2.4 技术栈模板按框架快速初始化这是模板库的价值放大器。我维护了一套按技术栈划分的初始化模板比如nestjs-service、react-component-lib、python-data-pipeline每个都是针对该技术栈的 CLAUDE.md 骨架、命令集和依赖审查规则。新项目启动时我只需要把对应技术栈模板复制过去改改项目概览就行。以前搭建一个 AI 的项目认知要我一上午现在五分钟搞定而且每用一次模板本身还会根据新项目的实际反馈迭代。这个思路其实非常像代码领域里的脚手架工具一个是生成代码骨架一个是生成 AI 协作骨架。3. 手把手搭建自己的模板库目录结构与关键文件写法3.1 我推荐的模板库目录结构先把目录摊开这是我目前稳定使用的结构claude-code-templates/ ├── base/ │ ├── CLAUDE.md # 通用基础规则不含具体项目信息 │ ├── commands/ │ │ ├── review.md │ │ ├── test.md │ │ ├── refactor.md │ │ ├── debug.md │ │ └── commit.md │ └── skills/ │ ├── error-handling.md │ └── naming-conventions.md ├── stacks/ │ ├── nestjs-service/ │ │ ├── CLAUDE.md │ │ └── commands/ │ └── react-component-lib/ │ ├── CLAUDE.md │ └── commands/ └── scripts/ ├── init-project.sh # 一键初始化新项目模板 └── sync-templates.sh # 把更新同步到所有在用项目base放一切项目通用的东西stacks放技术栈特定的东西scripts放自动化脚本。这个分层最大的好处是更新通用规则不会碰坏技术栈规则技术栈规则升级也不会污染其他项目。3.2 一个可用的 CLAUDE.md 模板骨架具体到一个 CLAUDE.md 文件我建议你按下面这个十进制顺序组织顺序本身就是优先级# CLAUDE.md ## 1. 项目元信息 - 一句话说明项目价值、主要模块、关键外部依赖 ## 2. 核心命令 - 启动命令、测试命令、构建命令、lint 命令 - 这些命令必须准确AI 很可能高频使用 ## 3. 架构约定 - 目录如何分层模块间依赖方向 - 严禁的架构模式例如禁止循环依赖、禁止隐式全局状态 ## 4. 编码规范 - 语言特性使用边界 - 命名、格式、注释风格 - 错误处理、日志规范 ## 5. 测试与质量门槛 - 测试类型、覆盖率要求、测试数据管理方式 ## 6. 项目特定注意事项 - 历史包袱、已知坑点、遗留系统兼容我特别强调核心命令这部分。Claude Code 是以命令执行见长的工具如果它连你的启动命令都得猜后面每一步都可能是错的。把这个写在第二条能显著减少它在沙箱里瞎试的次数。3.3 自定义斜杠命令的格式与参数传递写斜杠命令文件有几个硬性的格式细节我第一次就栽了跟头。第一$ARGUMENTS是用户输入正文的注入点。比如用户敲/review src/modules/user.ts那src/modules/user.ts就会被替换进模板里的$ARGUMENTS。我在模板里必须写清楚如果没有给出参数则默认审查未提交的改动否则一个空参数会让模型愣住。第二斜杠命令文件里的---开头的 frontmatter 区域可以配置命令的元信息包括描述、是否允许参数等。这个区域不是摆设认真写 description 能让命令在列表里一眼可懂。第三命令模板本身不应该试图代替模型去完成动作而应该像一个高质量的需求文档定义清楚目标、约束、输入、输出格式。剩下的推理过程模型自己会完成。把模板写成逐字逐句的台词反而是个大误区。3.4 模板库的自动化加载与配置手动复制粘贴模板太痛苦了我用脚本来做初始化。init-project.sh的核心逻辑并不复杂接收一个技术栈参数然后从stacks目录拷贝对应模板到新项目根目录再把base里的通用命令一并合并。这里有个细节需要注意CLAUDE.md 文件在项目里是自动生效的但斜杠命令文件需要放在项目根目录的.claude/commands/下才会被识别。所以我脚本里的合并逻辑会特别处理这两个路径。另外如果项目是 monorepo每个子包可能还需要一份独立的 CLAUDE.md这份文件放在子包根目录即可它的优先级比根目录高。自动化的价值不只是省时间更重要的是一致性。手动操作一定会漏文件漏一个文件AI 的行为模式就断层了。用脚本后我每次初始化的项目AI 的入职状态都是被验证过的。3.5 模板的版本管理与复用策略好的模板库跟好的代码库一样要有版本和变更记录。我现在用 git 管理整个过程每个模板文件单独一个目录有独立提交历史。模板的更新走先改 base再跑 sync 脚本推送到在用项目最后收集反馈回滚或固化的循环。复用策略上我坚持一个原则公共的规则往 base 下沉特殊的规则往 stack 或者项目本地下沉。比如所有日志必须包含 requestId属于 base而本项目的 Kafka topic 命名必须以 某前缀开头属于项目本地。如果一级一级搞混了维护成本立刻翻倍。4. 常用模板场景实录我从模板库中提取的 6 个高频玩法4.1 代码审查模板让 review 从玄学变成清单代码审查是我每天用得最多的模板。核心技巧是把审查维度拆成硬性清单而不是让 AI 凭感觉挑毛病。我的/review命令会把审查对象分成几类改动 diff、单文件、整个 PR 分支。最常用的是 diff 模式它的输出我特别设计了三级结论PASS、FAIL、WARN。这个设计看着简单实际非常关键。没有结论等级的审查AI 会给你列出一堆建议优化项导致你根本分不清哪些必须改、哪些只是锦上添花。有了 FAIL 和 WARN 的区分团队协作效率立马上来了。还要避免一个常见的坑AI 在找不到问题时容易为了存在感编问题。所以我的模板里明确写了 如果改动较小且符合规范必须直接返回 PASS禁止为凑数提出无关建议。这行字看起来像是在约束 AI 的废话量实际上是在校准它的判断阈值。4.2 重构模板让 AI 做有纪律的搬运工重构类任务最怕的是 AI 一上来就大动干戈。我的/refactor模板内置了一个强制策略先请求重构方案说明再请求逐步执行每个步骤完成时必须通过测试。模板里的关键指令是禁止混入任何与目标无关的重构。这句话非常重要因为 AI 在重构一个函数时很容易顺手就把旁边的变量命名也改了行为没有变化但你 diff 变得巨大review 成本飙升。模板必须把这种顺手牵羊明确列为违规行为。我在实操中发现配合 CLAUDE.md 里的测试命令一起用效果最好。模板里注明每完成一个重构步骤必须执行核心测试集并汇报通过率AI 就会真的去跑测试而不是嘴上说应该没问题。4.3 自动化测试模板用模板消灭测试死角写测试往往不是 AI 不会写而是它挑着写。它倾向于写那些容易覆盖的 happy path对边界条件、异常路径、并发场景视而不见。我的/test模板会强制要求它按照功能矩阵来产测试用例。模板里我写了一个测试计划骨架每一个函数要列出正常场景、空值场景、极致边界、错误输入、竞态条件五个维度至少各一个用例。AI 一旦被这个矩阵约束产出的测试质量会跨一个台阶。另一个小心得是让 AI 在测试文件头部用注释写清楚被测对象的行为假设。如果假设本身跟实现冲突测试用例就会失败这个失败其实是在帮你发现需求理解的偏差。这个视角跳出了写测试本身变成了验证需求一致性。4.4 新项目接入模板五分钟让 AI 上岗我把stacks/nestjs-service这类技术栈模板与新项目初始化脚本配合做了一套一键上岗流程。脚本会把 CLAUDE.md 里的项目概览部分改成可填空的占位符然后提示我输入项目名和技术选型自动生成最终的规则文件。新项目接入模板的另外一个隐藏价值是它顺带充当了团队新手文档。新同事来了我不用带他念 wiki直接让他把这个模板库克隆下来跑一遍初始化脚本他对项目的认知框架就有了。AI 的新人培训和人类的新人培训居然用了同一套材料这个收益是我当初完全没想到的。4.5 Bug 排查模板先把症状和病因分离写 Bug 排查模板时我最想解决的是 AI 一上来就乱猜原因的问题。/debug模板里我设计了强制的信息收集顺序先收集复现步骤、期望行为、实际行为、最近改动然后才允许生成假设列表。模板末尾我会写上这样一句在生成最终结论之前必须列出至少两个互相矛盾的假设并解释为什么选择其中一个。这一招的灵感来自工程上常用的反面论证。它强迫 AI 不急着下结论而是先审视自己的推理盲区。实测下来这个模板让 AI 对疑难 bug 的定位准确率提升明显。4.6 Commit 信息模板把散装代码变成有序叙事这种小模板最容易被忽略但收益是最直接的。我的/commit模板会让 AI 先读取当前 diff再读取 CLAUDE.md 里的提交规范然后按照格式 范围 一句话描述的结构生成提交信息并且拆分出 summary 与 body。这里一个比较有用的细节是模板要求 AI 生成三个候选提交信息分别偏重精简完整面向 reviewer 解释原因三个风格。我每次挑一个最顺眼的省去自己憋 message 的时间。这种轻量级模板是整个体系中性价比最高的投资。5. 模板编写避坑指南与问题排查5.1 模板太长反而失效上下文预算问题我见过最夸张的一个团队模板CLAUDE.md 超过一万字几乎把公司开发规范文档全抄了进去。结果是什么呢模型确实知道所有规则但它在具体任务中频繁地想不起来用正确的规则因为它要在海量上下文里大海捞针。这里面的原理其实不复杂AI 处理长上下文时注意力会被稀释后面的规则容易淡出。所以模板必须做瘦身把高频规则放在最前面低频细节放到单独文档里再在 CLAUDE.md 里写一句遇到 X 问题时请阅读 docs/xxx.md 的相关章节。用索引代替内联是我踩过最深的坑之后的头号经验。5.2 通用与特化的平衡写模板很容易滑向两个极端要么完全通用放在任何项目都行结果对特定项目屁用没有要么完全特化只对这个项目的某个目录有效换项目就得重写。我的平衡方法是三层漏斗最底层是 base 的通用守则只涉及所有软件项目都适用的大原则中间层是 stack 的技术栈细则比如 NestJS 项目特有的依赖注入约束最上层是项目本地的具体约定。每一层只关注自己职责范围内的事严禁越界。这个设计让模板的维护量下降了一个数量级。5.3 变量替换、引号与转义问题斜杠命令模板里如果涉及代码示例一定要小心引号和变量名的冲突。举个例子命令模板中要展示一行 Bash 代码恰好里面包含了$ARGUMENTS这种字符串就可能被 Claude Code 当成参数注入点导致执行时被替换得面目全非。我的处理方式是在模板示例代码里避免原样书写$ARGUMENTS字样实在要提参数时用用户输入的参数这句话带过或者用反斜杠转义。这类问题排查起来特别隐蔽因为模板看起来完全正常但输出里的变量全被替换掉了。你要是在用某个模板时发现参数莫名丢了一段先怀疑这个。5.4 常见问题排查速查表我自己维护了一个模板问题的排查清单这里直接分享出来现象大概率原因处理建议模板没生效AI 行为与之前完全一致文件路径不对或文件名拼写有误检查.claude/commands/下的文件名CLAUDE.md 必须在项目根目录模板生效但效果很差模板太长关键规则沉到上下文底部把最关键的规则提到文件前三段命令可以执行但参数没传进去模板里错误使用了$ARGUMENTS或参数中包含特殊字符检查模板原文必要时给参数加引号同一个模板在不同项目表现不一致项目本地 CLAUDE.md 与模板规则冲突用项目本地规则默认覆盖的原则梳理冲突优先级更新 base 模板后项目行为没有变化项目里的旧模板没有同步覆盖用 sync 脚本强制同步并检查文件更新时间戳5.5 模板迭代的反馈闭环最后说一个软性的但非常重要的经验模板一定要迭代而且迭代的依据是失败案例而不是爽快体验。我每次遇到一次 AI 的明显失误会先问自己:这是模型能力问题还是我模板里没有对应的约束八成情况是后者。我会把这次事故写成一个负面案例补进相关模板的禁忌部分。比如我遇到过 AI 在迁移数据库脚本时把外键约束弄丢了之后我就在所有涉及数据库改动的模板里加了一条硬性约束任何涉及表结构的改动必须同时输出完整的外键和索引维护方案。模板库本质上是一个团队的经验库每一条规则背后都应该有一个真实的事故。没有事故支撑的规则都是在给 AI 增加噪音。这个理念贯穿了我全部模板的维护过程。我琢磨了挺久之后的一个体会是把 Claude Code 用明白这件事真正比你模型强弱更大的杠杆其实是你有没有一套值得它入职的体系。模板这个东西投入产出比是被严重低估的。它不是什么科技含量拉满的东西需要的就是你愿意把那些天天重复的规则、命令、禁忌认认真真写进文件里然后逼自己遵守先写模板再干活的纪律。如果你现在还处在每次会话都要把项目背景重新敲一遍的状态那今天的目录结构、命令模板和 CLAUDE.md 骨架你直接拿来改一改就能用。等你的模板库积累了三个月再回头看第一个手写 prompt 的日子应该会跟我当时一样长舒一口气。