Claude Code模板搭建指南：从全局配置到技能包，让AI真正懂你的项目

1. 为什么需要Claude Code模板不配置和配置的差距我大概是从去年开始重度用Claude Code写日常业务代码的。头两个月我对它的评价很矛盾一方面它确实能在终端里完成不少机械活另一方面我总觉得它像个记性很差的新同事——每次开会都要重新介绍一遍项目刚说完的技术栈转头就忘生成的代码风格和我自己的习惯总是差半拍。直到我认真梳理了一套基于claude-code-templates思路的模板体系这个局面才彻底改观。先说一个最典型的场景。我接手过一个TS写的monorepo里面有十几个package后端是NestJS前端是React还混着几个给数据团队用的Python脚本。最早我没配任何模板直接让Claude Code帮我加一个接口结果它把代码写进了错误的package还用了和项目完全不同的缩进和命名风格。不是它不努力是它真的不知道这个仓库有几层、每个目录干嘛的、代码规约是什么——这些信息全散落在几十个配置文件和文档里它每次会话都要靠猜。后来我把这些信息固化成了模板同样的需求再提给Claude Code它会在动手前主动确认按service层的现有模式实现错误码用项目统一枚举产出的代码几乎可以直接合进MR。这就是模板的价值它不是给AI念一段更长的咒语而是把项目里那些默认就该知道的东西提前放在它能读到的地方省掉每次对话里反复交代的沟通成本。这篇文章我打算完整讲讲自己搭这套模板的来龙去脉模板体系怎么分层、每个文件到底该写什么、哪些配置坑了我一整天以及模板维护的节奏怎么定。适合已经开始用Claude Code、但觉得它还不够懂你的开发者——尤其适合在多项目、多语言环境里工作的人。2. 一套实用的模板体系长什么样三层结构很多人在网上找模板下了一堆别人分享的CLAUDE.md粘贴进项目发现效果一般。原因多半是别人的模板解决的是别人的问题硬套过来自然别扭。我自己折腾下来一个好用且能长期维护的模板体系应该是三层结构各管一摊互不干扰。2.1 第一层全局配置管住你自己的代码风格这一层对应~/.claude/CLAUDE.md具体路径看你用的版本它描述的是你这个人怎么写代码而不是某个项目怎么写代码。比如我常年写Python和TypeScript我自己偏好类型标注齐全、函数尽量短小、注释只解释为什么不解释是什么这些偏好不需要每个项目重新说一遍。全局配置里我建议固定这几类内容通用语言偏好默认语言、命名风格、缩进习惯默认工作流先读测试再写实现、改动前先列计划通用禁忌不主动引入新依赖、不重构没被要求的代码、不在提交里夹带调试输出这层配置写好之后你在任何项目里和Claude Code对话它都自带你的底色。我见过一些人把这层配得非常长连框架选型都写进去这就过界了——框架选型是项目的事不是个人的事放错层级后面会很麻烦。2.2 第二层项目级配置告诉AI这个仓库的内部规则项目级配置通常放在仓库根目录的CLAUDE.md也可以引用docs/claude/下的多个分文件。这层解决的是这个项目特别在哪里。它应该包含仓库结构地图核心目录各自负责什么新增代码应该落在哪技术栈清单框架版本、包管理器、构建工具以及哪些不能用代码规约的本地化错误码体系、日志规范、数据库迁移的写法常用命令跑测试、跑lint、起本地环境的命令省得AI每次瞎猜我第二个项目就把这块写成了新成员入职手册的格式。为什么是这种格式因为Claude Code每开一个新会话本质上就是一个从头开始的新成员你希望新人第一天知道什么就该写进项目模板里。官方文档里可能建议你写文件位置但我建议你把文件位置换成职责清单AI理解这个目录是用来放定时任务的比理解这个目录叫jobs有效得多。2.3 第三层可复用的技能包与临时模板把高频操作固化下来第三层是可选的但恰恰是最能拉开效率差距的部分。你可以建一个templates/或skills/目录把给API加一个带鉴权的端点写一个带迁移文件的Django model按项目规范创建一个新的React组件这类高频任务写成带占位符的模板文件。Claude Code能通过特定机制加载这些技能相当于给它装了一批固定招式。举个例子我的一个项目里后端每次新增一个gRPC接口都要走四步改proto文件、跑代码生成、写service实现、补单元测试。之前我每次都要在对话里把这四步说一遍AI偶尔还会漏掉其中一步。后来我把这四步写成一个技能模板附上每一步的参考文件路径和常见错误之后只要说按模板新增一个GetUser的gRPC接口它就能按固定顺序走完输出质量稳定了很多。三层结构的核心逻辑是让每一层的关注点尽量单纯全局管风格项目管事实模板管流程。任何一个信息你都要问一句它是谁的事放对了层级模板才不会越写越乱。3. 从零搭建一套可复用的模板目录完整实操理论讲完下面是我自己在干净环境里从零搭这套模板的实际步骤。我会把目录结构、文件内容、怎么让Claude Code读到它们都过一遍你可以直接照着抄。3.1 先搭好顶层目录别急着写内容我建议先建一个独立的配置目录比如~/.claude/然后在里面分三个子目录~/.claude/ ├── CLAUDE.md ├── skills/ │ ├── add-grpc-endpoint/ │ │ ├── SKILL.md │ │ └── examples/ │ └── new-react-component/ │ ├── SKILL.md │ └── templates/ └── templates/ ├── commit-message.md └── code-review-checklist.md先搭目录而不是先写内容是为了让你强制思考我到底需要哪些模板。我见过一上来就写了两千字CLAUDE.md的人里面一半内容AI根本用不上还占满了上下文窗口。目录结构就是你的体系地图先规划再动笔后面维护轻松很多。3.2 全局CLAUDE.md的写法按规则—原因—示例三段走全局文件不用长但每条规则最好都给出原因和示例。纯命令式的规则AI容易照字面执行出离谱结果带原因和示例的规则它才能做判断。我当时写的全局CLAUDE.md核心部分长这样# 个人编码偏好 ## 规则 - Python代码必须带完整类型标注函数返回类型不能省略。 - 原因项目里mypy作为CI检查的一部分漏标注会直接让流水线变红。 - 示例def parse_config(path: Path) - dict[str, str]: - TypeScript代码优先使用interface而非type。 - 原因团队习惯用interface表达对象契约便于IDE提示。 - 不允许为了通过lint而全局禁用规则。 - 原因lint规则是团队讨论的结果绕过会让代码持续腐化。 - 所有日志使用结构化字段不要拼字符串。 - 原因日志系统按字段索引拼字符串会导致检索不到。 ## 工作流偏好 - 改代码前先用一句话说明计划得到确认后再动手。 - 涉及多个文件改动时逐个文件给diff不要一次性全改完。 - 提交信息遵循统一格式type(scope): subject。写到这里你可能会发现这不就是在给AI洗脑吗其实换个角度想你带了一个很聪明但没有行业常识的实习生你会希望他一上来就懂这些规则吗规则写得越具体AI就越能像团队里的老手一样工作。我建议规则总数控制在15条以内超过这个数AI的注意力会被稀释效果反而不如只选最关键的那些。3.3 项目级模板的经典写法把项目事实排序放好项目级CLAUDE.md写起来比全局的还要小心因为这里的信息直接决定AI生成的代码能不能编译、能不能跑。我通常按下面的顺序组织内容每个部分都不超过十条要点# 项目背景 - 这是一个面向内部运营人员的可视化报表平台。 - 前端React 18 Vite后端Node.js Fastify数据库PostgreSQL。 - 仓库有两个子包web前端和server后端共享代码放packages/shared。 # 关键目录 - server/src/routes所有路由定义新增接口必须在此注册。 - server/src/services业务逻辑禁止在路由里写复杂分支。 - web/src/pages页面级组件小部件放web/src/components。 - packages/shared前后端共享的DTO与类型定义改动会影响两个端。 # 代码规约 - 错误码统一使用ERR_开头的枚举见server/src/constants/errors.ts。 - 所有数据库查询必须通过仓库层repositories不允许直接写SQL。 - 前端组件必须用styled-components禁止引入CSS Modules。 - 测试统一用vitest文件命名*.test.ts。 # 常用命令 - pnpm install安装依赖 - pnpm dev启动本地开发 - pnpm test -- run跑测试 - pnpm lint检查代码这里有个细节我写目录职责时特意用了禁止这个词。AI对否定表达的理解比想象中要可靠你告诉它能去哪不如同时告诉它不能去哪。比如不允许在路由里写复杂分支这句话帮我避免了好几次AI把业务逻辑堆在路由文件里的情况。而且我建议项目模板里列出的常用命令一定要自己跑过一遍。我踩过一个坑模板里写的测试命令是npm test但项目里实际用的是pnpm vitest runAI按照模板跑了一个根本不存在或结果不同的命令白白浪费了十分钟排查。3.4 把高频操作固化成技能包附上一个可以抄的例子技能包是模板体系里最容易出效果的部分它让AI不仅能知道规则还能按流程办事。我给一个我们实际在用的示例# 技能新增gRPC端点 ## 适用场景 需要在server中新增或修改gRPC接口时使用。 ## 执行步骤 1. 修改 proto/user.proto新增message和rpc定义。 2. 运行 pnpm gen:proto 生成Go代码确认无报错。 3. 在 internal/service/user.go 中实现对应方法。 4. 在 internal/api/grpc/user.go 中注册handler。 5. 运行 pnpm test -- internal/service/user_test.go补充用例。 ## 常见错误 - 忘记在auth拦截器白名单中放行新接口导致调用方收到PERMISSION_DENIED。 - proto字段名未使用snake_case和已有的命名约定不一致。 - 生成的pb文件未重新编译就提交出现NewMethod不存在之类的编译错误。 ## 参考示例 见 examples/add-role-endpoint/ 目录含完整diff。有了这个技能我再提需求时只需要说用新增gRPC端点的技能加一个GetUser接口AI就会自动按步骤走。它甚至会在第一步主动检查proto文件里有没有同名接口防止重复定义。这对AI来说不是多聪明的操作但借助模板把流程固化下来效率和稳定性确实提升了一个档次。3.5 让Claude Code加载模板的关键配置这一步很多人会卡住。模板文件放好了但AI完全无视多半是加载配置没写对。以我用的配置方式为例我检查三项全局模板确认文件路径在~/.claude/下且名字叫CLAUDE.md或者通过命令行参数显式指定路径。项目模板确认在当前项目根目录有CLAUDE.md或者被导入的路径写对了。技能包确认每个技能目录有SKILL.md或等效的元信息文件AI才能识别这是一个可加载的技能。我自己常用的一个技巧是在配置中显式声明模板的引用路径尽量用绝对路径而不是相对路径避免AI在嵌套目录下解析出错。如果发现AI始终读不到某个模板可以先在对话里直接问路径是否存在这一步能省掉大量猜测时长。4. 模板生效机制与我最想吐槽的五个坑模板配好之后真正用起来的第一个星期我踩了一堆不大不小但特别磨人的坑。这部分是我最想分享的因为这些坑几乎不在任何官方文档里。4.1 加载优先级全局、项目、技能到底谁覆盖谁模板不是一个全部读进来的黑盒子Claude Code在不同层级的信息之间是有优先级关系的。我实际测试下来项目级模板的信息比全局模板更贴近当前任务技能包则是在命中的时候才会加载。这个机制意味着如果你在全局模板里写了TypeScript用interface而项目模板里写了TypeScript用type那么项目里生效的应该是项目模板那一条。如果发现AI有时按老的全局规则做事别忘了检查是不是全局规则写得更具体或更靠后它偶尔会按离任务更近或表述更明确的那条来。4.2 坑一模板文件用了相对路径导入AI在子目录里读不到我第一次组织项目模板时把仓库结构说明拆成了一个单独的docs/architecture.md然后在CLAUDE.md里写详见docs/architecture.md。看起来没问题但当我让AI处理server/src/routes下的任务时它把相对路径解析成了server/src/routes/docs/architecture.md自然什么都读不到。解决办法很简单要么把拆分的小文件统一放到一个固定目录比如docs/claude/下并在模板里用绝对引用或固定的根路径锚点要么干脆把这些内容直接写进根目录的CLAUDE.md不折腾拆分。对大多数项目来说一个结构清晰的单文件完全够用拆得太碎反而让AI在寻路上浪费时间。4.3 坑二模板太长把上下文窗口塞满了我见过有人把项目所有历史决策、每条API的说明、每个模块的设计文档全部塞进模板。Claude Code的上下文是有限的模板太长了留给对话和代码的空间就会变少AI甚至会因为信息过载而忽略中间部分。我自己的经验是严格控制模板体积。全局CLAUDE.md控制在40行以内项目CLAUDE.md控制在80行以内技能描述控制在50行以内。超出这个量就说明你写的不是模板而是文档库——文档库应该在需要时按需引用而不是一股脑塞给AI。具体操作上我会把真正长篇幅的内容放在单独的markdown文件里在模板中只写处理XX任务时先读docs/claude/xx.md让AI在需要时主动去读这样既保留了完整信息又不占用日常对话的上下文空间。实测下来这个按需加载的做法比把所有内容平铺在模板里效果好得多。4.4 坑三模板内容和代码库脱节愈改愈乱模板是一个会过期的东西。我一开始把它当成了写一次就完事的文档结果三个月后项目从CJS切换到ESM模板里还在指导AI用require()写代码生成的东西一跑就报错。维护模板的节奏取决于项目变动频率。我的经验是每次依赖大版本升级、目录结构调整、代码规约变化时顺手改掉模板里对应的部分。如果你像我一样有比较规律的更新节奏甚至可以给模板加一个版本号标注最后更新时间这样AI读到模板时能判断它是否还有效。4.5 坑四共享技能里混入了个人信息被提交到公开仓库这个坑比较尴尬。我把一个写代码审查的技能模板直接复制到了公司的公共仓库里里面有一段评审时优先审查登录和支付相关代码那是从我个人项目带过来的和公司项目八竿子打不着。结果不但没起好作用还误导了AI在无关项目里过度关注特定模块。所以我现在养成了一个习惯模板准备提交到共享仓库之前一定先用脚本扫一遍占位符把所有项目特定的路径、模块名、个人偏好全部替换成通用说明。技能模板里的示例代码更要注意它最好来自当前项目的真实代码而不是网上抄来的通用片段。4.5 坑五模板更新后AI还在用旧规则像没改过一样这个问题一度让我很崩溃。我改了项目模板里的测试命令但AI在后续会话里还是给出了错误命令。后来我才意识到它可能在会话开始时就已经缓存了旧模板我只改了文件但没让它重新加载。遇到这种情况最直接的办法是开一个新会话或者用命令显式刷新上下文让AI重新读取模板文件。如果是多人协作还要确认所有人都用的模板确实是从同一个路径拉的有人本地有一份旧备份改了半天等于改了个寂寞。5. 模板从能用到好用我总结的几条实操心得前面的路子走通之后我慢慢将模板打磨成了一套比较顺手的工具。下面这些心得更像软性经验但对我帮助很大。5.1 模板是对话的默认上下文不是万能药再好的模板也替代不了清晰的指令。模板负责让AI处于正确的工作状态但你仍然要用一句话说清楚做什么、接受标准是什么。我之前一度以为配好模板就能撒手不管结果AI发挥得时好时坏后来才发现默认上下文优秀和目标清晰是两回事两者缺一不可。打个比方模板相当于给新同事发了一份团队手册和代码规范但他接手具体任务时你还是得告诉他修哪个bug、预期什么行为、怎么验证。模板降低的是沟通成本不是沟通本身。5.2 用模板做自动化审查效果出乎意料我后来把模板从生成代码扩展到了审查代码。在模板里增加了一个用于Code Review的技能让AI按检查清单审查我的diff有没有未处理的错误分支、有没有破坏现有API签名、测试覆盖率是否达标。这个用法实测下来非常香它甚至能发现一些我潜意识里知道但懒得改的小毛病。比如有一次我改了一个公共函数签名变了但调用方没全改我自己review两遍都没注意到AI按模板里的检查所有调用点这一条几分钟内就把漏掉的调用方全列出来了。这个过程让我意识到模板的重点不只是让AI听话干活也是让AI承担一部分团队制度的执行角色。5.3 模板之间的依赖要尽量减少保持每个文件的独立性早期我为了少写重复内容在好几个技能模板里互相引用比如参考add-grpc-endpoint中的步骤。结果AI在加载时经常漏掉被引用的模板或者加载顺序不对导致技能失效。后来我把每个技能都写成自包含的哪怕重复了几行说明也不去依赖别的技能。这个做法让每个技能都能独立工作也方便单独调试、单独复制到其他项目。从工程角度看模板也是一种代码内聚性高于复用性对AI这种上下文敏感的执行者来说尤其重要。5.4 定期用AI审AI的模板防止体系僵化每过一两个月我会做一次模板体检把当前的模板文件拖进一个新会话问它根据这些规则如果我要新增一个模块你会按什么步骤走。通过它的回答我能发现模板里过时的、矛盾的、或者写得模糊的地方。这个方法比自己通读模板有效得多因为AI会暴露那些看似写了但其实没写清楚的瑕疵。比如我就发现过一条合理处理错误AI完全不知道该怎么做才算合理拆成统一使用ERR_枚举并记录日志之后执行质量立刻好了很多。写模板最忌讳的就是只给原则不给操作AI对模糊表述的理解有时候比你我更字面。6. 模板放出去之前我还想提的三个小建议聊点收尾的内容不是总结是我后来在更多项目里复用这套模板时攒下的几点建议想到哪说到哪。第一模板不是越全越好它是上下文的提词器而不是百科全书。信息密度过高的模板会让AI在关键信息上反而不敏感精简之后效果往往更稳定。我在两个项目里分别试过精简版的模板生成的代码质量反而更高因为它能把注意力集中在最重要的几条规则上。第二如果团队一起用一定要把模板纳入版本管理。模板的改动应该像代码改动一样被review、被记录。我见过团队里有人偷偷改了自己本地模板导致不同人跑出完全不同的AI行为最后代码风格又分裂了。让模板和大家看到的代码规范保持同步是整个协作能长期进行下去的基础。第三善用社区里的现成模板但别照抄。网上的awesome-claude-code-templates这类仓库可以给你很多灵感但你需要把里面的内容逐一过滤哪些是自己项目真的用得上的哪些是作者个人偏好。我最初也下了几个高星模板最终留下的其实只有一两条规则。这很正常模板的最终形态就应该高度个人化、项目化。如果你现在正好觉得Claude Code不太好使先别急着怀疑模型能力花一个下午认认真真把模板体系搭起来把项目的基本盘交给它。你可能也会发现一个懂规则的AI跟一个只知道努力但连项目背景都不了解的AI使用体验完全是两个世界的事。