最近在折腾 Claude Code 的时候我发现自己花在“教 AI 怎么干活”上的时间快要赶上“让 AI 干活”本身的时间了。每次新开一个项目都要重新跟它解释一遍代码规范、目录结构、常用命令遇到团队协作时更痛苦每个成员的 Claude 行为都不一样。直到我把 templates 体系认真搭起来这个局面才算彻底改观。这篇东西就是冲 claude-code-templates 来的。Claude Code 的模板不是花架子它是一套能让 AI 编程从“碰运气”变成“按流程走”的规则引擎。无论你是一个人写 side project还是带着小团队做商业项目只要你想让 Claude 稳定输出、少犯低级错误、风格统一那这套模板方案就是绕不开的基础设施。我会从为什么需要模板讲起然后逐层拆解 CLAUDE.md 规则模板、slash command 命令模板、以及工作流模板的设计和落地方案最后把我在实际项目中踩过的坑一并倒出来。内容会比较干但每一步你都可以直接抄作业。1. 内容整体设计与思路拆解1.1 为什么 Claude Code 需要模板体系先问一个问题你在终端里敲claude之后这个 Agent 凭什么知道你的项目该怎么处理它确实能读代码、能跑命令、能自己规划任务但它的“默认人格”是通用的不是专门适配你和你的项目的。没有约束的情况下你会发现它经常干这些事明明项目用 pnpm它偏要给你npm install说好了变量命名用 camelCase它偶尔给你整出 snake_case重构到一半它自作主张把没关联的文件也顺手改了。这些问题本质上不是 AI 能力不够而是缺少一套“行为契约”。templates 就是这份契约的载体。把项目的规矩、偏好、禁忌、工作流全部写进模板Claude 每次启动时先读规则再干活行为自然就稳定了。而且模板的意义不止于“约束”。它还是记忆的扩展。Claude Code 的上下文窗口是有限的你不可能每次对话都长篇大论描述项目背景和业务逻辑。模板相当于给它装了一个“外置硬盘”把约定俗成的背景知识全存进去需要的时候自动加载。1.2 模板体系的分层架构我搭这套模板体系时不是随手扔几个 md 文件进去就完事了而是按照“全局 - 项目 - 会话”三个粒度来做分层设计第一层是全局模板也就是~/.claude/CLAUDE.md它管的是你个人的通用编码偏好。不管你在哪个项目里启动 Claude Code它都会先加载这份文件适合放下跨项目通用的规则比如提交信息的格式、默认语言、通用工作流偏好。第二层是项目级模板放在项目根目录的CLAUDE.md里它管的是当前这个仓库的具体约束。项目是什么、目录怎么组织、测试怎么跑、构建命令是什么全部写在这一层。这一层最核心后面我会花大篇幅讲。第三层是基于 slash command 的会话级模板。它不常驻而是通过/命令名的形式按需触发比如/refactor、/review、/test适合封装高频的专项任务流程。这个设计让 Claude 在需要时“切换角色”而不是永远一套打法。这三层各司其职叠在一起就是你给 Claude 定制的完整操作系统。我见过很多人只放一个项目级 CLAUDE.md 就觉得完事了短期看能解决一部分问题但一旦项目复杂起来缺少全局层和命令层模板会越写越臃肿最后什么都管等于什么都没管。1.3 模板设计要回答的三个问题在动手写任何模板之前先想清楚三个问题后面每写一段规则都对照一遍模板就不会跑偏。第一个问题我希望 Claude 在任何情况下都不做什么。这是红线思维。比如“不要修改锁定文件”“不要动 migration 历史目录”“未经过确认不得删除任何文件”这类规则优先级最高必须放在模板显眼位置。第二个问题我希望 Claude 在这个项目里做什么事的时候遵循什么流程。比如“新增功能时先写测试”“改动数据库结构需要同步更新 ER 图”“联调接口之前先 mock”。流程类规则要写得像操作手册步骤明确顺序清晰。第三个问题我希望 Claude 的输出长什么样。这包括代码风格、命名规范、注释习惯、commit message 格式。输出规范类规则最细碎但也最容易见效因为它的效果是你肉眼可见的。想清楚这三件事模板的骨架就出来了。接下来每一行规则都要归到这三类之一归不进去的内容就不要写写了反而稀释核心规则的分量。2. 核心细节解析与实操要点2.1 CLAUDE.md 的语法与文件结构CLAUDE.md 的语法本质上是 Markdown没有太多特殊花样但它有一个很关键的加载规则优先级按文件作用域来越具体的覆盖越宽泛的。全局配置是底线项目配置在底线之上做增量调整而当前会话里的/clear之后重新声明的内容又可以临时覆盖。文件放置的位置也是有讲究的~/.claude/CLAUDE.md全局用户级规则适合跨项目的偏好。项目根目录/CLAUDE.md项目级规则会被 Git 跟踪团队共享。子目录也能放 CLAUDE.mdsrc/api/CLAUDE.md当你让 Claude 专门处理某个模块时它会优先参考这个子目录的规则。导入子文件主线 CLAUDE.md 可以用灰常简单的path/to/file语法引入其他说明文档比如把架构说明放 docs 里主文件只保留行为规则。结构上我习惯分成Identity身份、Context背景、Rules规则、Workflow流程四块。身份告诉 Claude 它在这个项目里扮演什么角色比如“你是一名资深 Go 后端工程师”背景交代项目业务逻辑和技术栈规则列禁忌和强制项工作流给出执行任务的标准路径。顺序也很重要。规则要放在最前面还是最后面其实有讲究。我个人验证下来CLAUDE.md 的开头区域影响力最大所以最重要的红线规则一定要放在文件前三分之一的位置。后面跟背景介绍、命令说明这些“参考信息”不会占用 Claude 太多注意力但红线规则一旦被淹没后面出事的概率就会大很多。2.2 项目级模板的模块划分项目 CLAUDE.md 不要一上来就写“你必须遵守以下一百条规则”这种压迫感拉满的文档。Claude 吸收规则的速度快但它处理过度冗长的上下文同样会稀释注意力。我的做法是模块化拆解用表格和标题把内容分区让它快速定位到当前任务相关的那一小块。我会在项目模板里固定放这么几个模块项目概况与技术栈不超过五行。说明这个仓库是做什么的核心语言和框架包管理器是什么。代码风格与命名规范。结合项目实际写比如前端项目写明组件文件采用 PascalCase、工具函数采用 camelCase、样式类名采用 BEM。目录结构与模块边界。告诉 Claude 哪些目录不许乱动新增代码应该放哪里。比如 monorepo 项目里packages/ 下每个子包是独立的不能随意跨包引内部文件。常用命令速查。启动、测试、lint、build 分别是什么一条命令一行。这能省掉大量 Claude 反复猜测的时间。红线与禁止事项。写清楚哪些操作必须要用户确认哪些文件禁止修改哪些目录禁止重命名。这些模块看着平淡但如果每一条都写得具体组合起来效果非常惊人。比如写“组件文件采用 PascalCase”就同时需要写明components/user/UserCard.tsx是合理路径而components/user/userCard.tsx不合理这样 Claude 才能判断到底改成什么样才是符合规范的。2.3 写好规则的三条铁律模板规则的颗粒度把握是新手最容易翻车的地方。我总结了三句话规则要具体到动作不要停留在形容词。写“代码要整洁”等于没写因为 Claude 无法对“整洁”形成一致的执行标准。写“每个函数尽量控制在 50 行以内超过就要拆分”则是一个可执行指令。同样“不要写魔法数字”不如“常量定义放 src/constants 下禁止在业务代码里直接出现未命名的裸数字”。规则要给出反例正反结合。只说“命名要规范”Claude 还是拿不准给它正例和反例各一个它就理解得非常快。比如“接口返回类型请统一使用ApiResponseT包装不要直接 return 裸对象反例return{code: 0, data: ...}”。规则要定期裁剪去掉废话。你每给 Claude 增加一条规则都在消耗它的上下文注意力。如果某条规则写了之后从来没起过作用说明要么项目里根本遇不到这个场景要么规则写得模糊无效。这种规则果断删掉模板不是越厚越好。3. 实操演示三步搭好你自己的模板3.1 第一步从零搭建全局人格模板先打开~/.claude/CLAUDE.md这个文件是 Claude Code 的“出厂设置”。我一般会先写清楚自己的技术栈偏好和语言习惯比如我常年在 Node.js 和 Python 之间反复横跳就会写明“跨语言场景下优先考虑 TypeScriptPython 代码风格遵循 PEP8但类型注解必须完整”。全局模板里还会包含几个跨项目通用的工作习惯比如Git 提交信息统一使用 Conventional Commits 格式。修改代码时如果涉及破坏性变更需要在回复开头醒目提示 BREAKING CHANGE。面向用户的文案一律使用中文代码注释使用英文还是中文按当前项目 CLAUDE.md 为准。对于不确定的需求先列出假设清单让用户确认再动手写代码。全局模板不要写太细只放“你这个人默认怎么工作”级别的规则具体项目的规矩交给项目模板去覆盖。如果全局写太多种子切到某个不相关的项目时会显得很违和。3.2 第二步编写项目 CLAUDE.md 并挂接子文档新建一个项目时我默认就会建一个CLAUDE.md放在仓库根目录。以一个实际的中型前端项目为例我会这样组织它的内容# CLAUDE.md ## 项目身份 你是本仓库的资深前端工程师技术栈为 React TypeScript Vite包管理器为 pnpm。 ## 核心约束 - 禁止修改根目录下的 vite.config.ts 中的 alias 配置除非用户明确要求。 - 所有新组件必须放在 src/components 下按业务域分子目录。 - 禁止提交 src/generated 目录下的自动生成文件的相关改动除非需要更新基准。 ## 常用命令 - 安装依赖: pnpm install - 开发服务器: pnpm dev - 运行测试: pnpm test - 构建产物: pnpm build ## 编码规范 - 组件文件命名采用 PascalCase如 UserProfileCard.tsx。 - hooks 文件命名为 useXxx.ts且每个文件只导出一个 hook。 - 样式方案采用 CSS Modules禁止使用全局 class 污染。 - 代码中禁止出现硬编码的业务文案统一走 i18n。然后我会在docs/claude/下存放更详细的领域说明文档比如frontend-rules.md、api-guide.md并在 CLAUDE.md 里通过docs/claude/frontend-rules.md引入。注意导入的子文档不要放一些无关紧要的废话否则每次启动 Claude 都要加载额外上下文反而拖慢响应。写到这里顺便提醒一句CLAUDE.md 会被 Git 跟踪所以它天然就是团队共享的文件。提交前一定要让整个团队 review 过不要你一个人拍脑袋写一百条规则然后丢给所有人接受。规则数量越多团队执行成本越大最终会变成没人遵守的摆设。3.3 第三步自定义 slash commands 模板把高频任务封装成 slash command 是模板体系里提效最明显的一环。Claude Code 支持把命令模板放在.claude/commands/目录下。每个命令是一个 markdown 文件文件名就是命令名例如.claude/commands/review.md对应/review。它的执行逻辑很简单当你输入/review时Claude 会把review.md里的内容注入到当前会话上下文然后按照你写好的模板去执行。所以模板内容写得越结构化、越明确命令执行效果就越稳定。我举个例子.claude/commands/refactor.md的内容可以这样写你是一名资深代码重构专家。用户会提供需要重构的代码片段或文件路径。 你的任务 1. 先识别代码中的坏味道列出具体问题不要立刻动代码。 2. 和用户确认本轮重构目标可读性性能还是结构性调整 3. 给出重构方案和实施顺序每次只修改一个文件运行测试确认通过后再继续。 4. 重构过程中禁止改变业务行为有任何行为变化必须明确提示。 5. 完成后输出修改摘要和测试结果。这个模板一放进去我每次敲/refactor就能得到一个固定工作流的重构助手而不是每次都要重新描述一遍“你先分析再动手”。像/review、/test、/explain这些命令都可以依葫芦画瓢做出来。如果你的命令需要带参数也是支持的。模板里可以用$ARGUMENTS占位符接住用户输入的参数比如/commit 修复登录页的边界情况模板就能拿到“修复登录页的边界情况”这一段作为输入。不过参数化命令建议等基础命令都用熟了再折腾不然很容易把自己绕晕。4. 常见坑与排查技巧实录4.1 模板规则冲突Claude 到底听谁的这是使用 CLAUDE.md 之后遇到的最典型问题全局说“代码注释用中文”项目模板说“注释用英文”Claude 到底听谁的我实测的结论是项目级规则优先级高于全局规则。Claude Code 的上下文拼接顺序通常是系统提示、全局配置、项目配置、额外参数后面的内容对前面有补充覆盖作用。所以项目模板里写一句“本项目的注释语言一律使用英文不受全局配置影响”是压得住全局偏好的。但子目录级 CLAUDE.md 和根目录级 CLAUDE.md 冲突时情况会复杂一点Claude 有时候会混淆。我的建议是不要制造这种模糊地带一旦两个层级的规则存在矛盾就直接在更高层级文件里删掉或注明覆盖关系不要赌它的判断。4.2 上下文被模板吃干回复质量明显下降这个坑特别隐蔽。你把几十个文档全部进项目 CLAUDE.md启动一次加载好几万 token 的上下文然后你发现 Claude 的回复开始变得迟钝、频繁遗忘你前几轮说过的话。原因很简单模板占用的上下文太多了。解法也很粗暴模板必须瘦身。核心 CLAUDE.md 控制在几十行以内只保留高频规则。低频的领域知识全部放到子文档里并且只在任务相关时按需加载。slash commands 模板也尽量精简目标不是让模板把话说全而是让 Claude 知道去哪找信息。另外一个技巧是如果某些规则只对特定目录或文件生效可以考虑把这些规则塞进对应子目录的 CLAUDE.md 里而不是全局加载。比如src/legacy/CLAUDE.md里写明“这里的老代码不允许重构只允许修 bug”这样 Claude 只有在处理 legacy 目录时才会收到这条规则其他任务完全不受影响。4.3 规则写得越狠Claude 反而越缩手缩脚有人把 CLAUDE.md 写成了“禁止大全”动不动几十个“禁止”。结果 Claude 确实不踩红线了但它连正常的代码都不敢改了每一步都停下来问用户确认效率断崖式下跌。这个问题的根源在于规则缺少优先级和判断空间。“禁止”类规则只适合用来保护真正不可触碰的东西比如生产数据库结构、锁文件、密钥文件。日常编码的偏好和流程应该用“默认怎么做 特殊情况怎么处理”的方式来描述给 Claude 留出合理的判断余地。我自己会把规则分成 MUST、SHOULD、MAY 三级。MUST 是红线不出意外必须执行SHOULD 是默认行为有特殊情况可以偏离但需要用户知晓MAY 是可选的优化建议不强求。这个分级思路写进模板之后Claude 的行为就变得既有底线又不僵化。4.4 模板更新的同步问题项目跑起来了模板也搭好了过了一个月你改了目录结构、换了包管理器、或者废弃了某个模块然后突然发现 Claude 还在按旧模板的路径找不存在的东西。这是模板体系最大的维护成本。我的实践是给模板加上更新责任人。单人项目就是自己每次重构改动目录结构时顺手更新 CLAUDE.md团队项目就指定一个“AI 配置负责人”类似于以前管 CI 脚本的人。另外可以在 CLAUDE.md 顶部加一行“本文件最后更新日期”这样每次会话开始时你就能扫一眼确认它没有过期。还有一个打工技巧让 Claude 自己维护模板。每隔一段时间我会让它“阅读当前仓库结构对比 CLAUDE.md 中描述的项目结构和命令是否仍然准确输出差异清单”。这个任务非常契合 Claude 的能力几分钟就能产出一份模板更新建议省去很多手工核对的心力。5. 模板在多项目与团队协作中的落地策略5.1 用模板工厂统一新项目初始化我自己手里长期维护着五六个项目每个项目单独手写 CLAUDE.md 不仅耗时还容易越写越不一致。后来我把它们抽成了一个“模板工厂”也就是一个公开的模板仓库包含一套标准化的 CLAUDE.md 骨架、一堆 slash command 模板以及常见技术栈的规则片段。新项目启动时直接把这些模板复制过去然后改项目名、技术栈、命令说明这些变量五分钟内就有一份可以用的项目规则。这个做法跟平时我们用脚手架初始化项目一个道理先初始化再定制永远比从零手写好。我这个方案可以做得更顺滑一点。把项目模板仓库 clone 到本地写一个简单的 shell 脚本接受项目名和技术栈参数自动复制对应模板并替换变量。我实际用下来这个脚本虽然不到五十行但每次开新项目都能省下至少半小时强烈推荐。团队场景下这套模板工厂更有价值。新人入职不用再有人给他长篇大论讲项目规矩让他直接读 CLAUDE.md 就能快速对齐。代码审查的时候AI 生成的代码风格也天然统一reviewer 的负担大幅下降。5.2 同一仓库的多个子项目的模板隔离monorepo 环境是模板体系最能体现价值的地方。每个子项目都有完全不同的规矩前端包用 pnpm、后端包用 Gradle、文档库用 npm前端禁 jQuery、后端禁 Lombok。如果只靠根目录一个 CLAUDE.md根本管不过来。子目录 CLAUDE.md 在这里就派上大用场了。根目录的 CLAUDE.md 只写仓库级别的公共约定比如 commit 规范和分支命名。每个子包目录放自己的 CLAUDE.md描述自己的技术栈、命令、目录约束。Claude Code 在处理子目录文件时会自动携带对应的子目录规则相当于给每个子项目配了一个专属的 AI 行为摸板。不过 monorepo 里子目录模板和根目录模板的内容需要设计好边界。我的经验是凡是子模板里已经写清楚的规则根模板就别重复。重复会导致两个地方的规则出现微妙的措辞差异Claude 一旦发现冲突它就会花额外的推理成本在判断用哪个上面得不偿失。我在前面提过的那套模板工厂方案在 monorepo 里还可以开出子模板分支。比如维护一个go-service/CLAUDE.md一个react-web/CLAUDE.md新加一个子包时直接把对应模板复制进去再改业务描述。这样整个仓库的每个子项目都有 AI 可读的“项目说明书”而不是让 Claude 靠猜。5.3 模板里该不该放业务敏感信息这是个非常现实的问题。CLAUDE.md 会提交到 Git 仓库会被团队所有人 clone甚至有可能放进公开项目里。所以模板里绝对不能写数据库密码、API 密钥、内部系统地址这些敏感信息。那业务背景怎么写才安全我的做法是只写“业务概念的关系”而不写“业务系统的细节”。比如电商项目可以写“本仓库包含商品域、订单域、用户域订单域依赖商品域的价格快照”这是概念层面的描述对 Claude 理解代码就够了而不需要写“订单系统连接了 xx 数据库使用 xx 中间件”。如果确有必要在本地使用敏感背景信息Claude Code 也支持引用本地文件你可以把包含敏感信息的说明放本地路径并通过~/.claude/local-only/xxx.md的方式引入。这个文件不要放进 Git 仓库只留在你本地就能既享受模板便利又不泄露信息。最后再分享一点实际的感受从我个人的经验来看模板体系不是一次搭好就一劳永逸的它是“活”的配置。我几乎是每做完一个迭代就会顺手往 CLAUDE.md 里补充一条这次发现的新规则或者删掉一条已经用不上的旧规则。整个文件就像项目的第二份 README只不过它服务的对象从“人类开发者”换成了“AI 开发者”。如果你也想搭这套体系不用想着一步到位。先从最简单的项目级 CLAUDE.md 写起把技术栈、命令、红线这三样放进去跑一个礼拜。等发现问题再迭代再加 slash command再做全局层。模板不在多而在于每一条都能实实在在地改变 Claude 的行为。坦白说花两天时间把模板体系打磨好之后每一个工作日都会省回来。这事投入产出比非常高值得认真对待。