1. 一个让人忍不住收藏的起点为什么会攒下这套模板先说个我自己的真实场景。我刚把 Claude Code 接入日常开发的那段时间效率确实提升了不少但有个问题一直让我很抓狂——每次开一个新项目或者在新终端里启动会话我都得重新跟 Claude Code 交代一遍项目背景、技术栈、代码风格、哪些库不能用、提交信息要按什么格式写……讲得快一点它理解得还行讲得慢一点半天就过去了。最离谱的是如果某个会话里聊了太多内容前面的约束会被冲掉AI 开始自由发挥生成的代码风格跟项目里现有的代码完全不是一路的。后来我意识到问题不在 Claude Code 本身而在于我没有一套结构化的方式去管理它的上下文。我开始琢磨能不能把所有常用的规则、角色设定、工作流约定沉淀成一组可复用的文件于是就有了这套 claude-code-templates。这套东西解决的核心问题简单说就一句话把每次都要重新讲一遍的东西变成自动读取、随时生效的文件。它适合所有正在用 Claude Code 做真实项目、且觉得每次交代上下文很费劲的开发者。不管你是做前端、后端、移动端还是写脚本工具只要把模板的层级结构搭好后续新项目起步的效率能提升一大截。而且要注意Claude Code 本身对CLAUDE.md这套机制的支持已经相当成熟。它会自动读取用户目录下的全局配置和当前项目根目录下的项目配置把里面的内容作为系统级上下文注入对话。这意味着你只要把文件放在正确的位置哪怕一个字都不多说AI 也已经知道了你的底线和偏好。这套模板的本质就是把 Claude Code 的这个特性组织成一套可管理、可版本化、可分享的工程资产。接下来我就把这套模板的设计思路、目录结构、内容写法和落地过程中的坑全部摊开讲一遍。2. 模板不是单个文件是一套分层体系很多人一想到给 AI 编码工具做模板第一反应就是在项目根目录放一个CLAUDE.md完事了。但真实项目里单靠一个文件根本撑不住。项目文档一长几百行塞进去AI 的注意力会被稀释重要的规则反而被淹没。我的做法是把模板拆成分层结构每一层只管一类事情。2.1 分层设计的核心思想按作用域拆按关注点分我用的分层结构是这么划分的层级文件/目录位置职责全局层~/.claude/CLAUDE.md所有项目的通用编码规则、安全红线、沟通风格项目层项目根目录/CLAUDE.md当前项目的技术栈、目录结构、命名规范、常用命令子命令层~/.claude/commands/或项目.claude/commands/高频重复操作如 code review、写测试、生成变更日志技能层~/.claude/skills/或项目.claude/skills/需要深度上下文的工作流如接入新 API、迁移旧代码自动化层项目.claude/hooks/触发式操作如提交信息检查、代码格式化前处理你可能会问为什么子命令和技能层的模板也要纳入进来因为它们本质上也是预先写好的指导剧本。一个/code-review命令内部其实就是一段精心设计的提示词要求 Claude Code 按照某个顺序检查代码输出特定格式的评审意见。这不就是模板吗2.2 为什么不能只依赖项目根目录的单个 CLAUDE.md我最早犯的错就在这里。最初我写了一个 300 行的CLAUDE.md里面既有不要用 console.log 调试这种基础规则又有跨服务调用必须走网关这种架构约束还带了各种代码示例。结果是什么呢Claude Code 确实会读取这个文件但它在生成长代码时注意力会被大量的规则分散尤其是那些互相交叉的规则经常出现执行偏差。更麻烦的是文件越长AI 在上下文窗口里记住的效力就越差到了会话后期基本等于白写。后来我想明白了模板的颗粒度应该跟关注点匹配。全局规则放全局文件里项目专属细节放项目文件里一段超过 20 行的操作流程就别写进配置文件里了直接用子命令封装。这样每份文件的职责单一、内容精炼AI 读取时能准确抓取核心指令执行效果也稳定得多。2.3 模板目录的推荐工程形态如果你在建自己的模板仓库我的目录结构是这样的claude-code-templates/ ├── global/ │ └── CLAUDE.md # 全局规则软链到 ~/.claude/CLAUDE.md ├── projects/ │ ├── frontend-template/ │ │ ├── CLAUDE.md # 前端项目模板 │ │ └── .claude/ │ │ ├── commands/ # 项目级子命令 │ │ ├── skills/ # 项目级技能 │ │ └── hooks/ # 项目级钩子 │ ├── backend-template/ │ │ └── ... │ └── cli-tool-template/ │ └── ... └── shared/ ├── commands/ # 通用命令如 /code-review └── skills/ # 通用技能如 /security-audit有了这个仓库结构新建项目时只需要把对应行业模板拉进去再根据项目特点做少量调整不需要从零写规则。这套思路跟工程化里的脚手架是一回事只不过脚手架管的是文件骨架这里管的是 AI 协作规则。3. 以前端项目为例拆解一套可落地的模板骨架光说理论太虚我拿前端项目模板来实际拆一遍。这个模板是我自己在用的把它复制到任何 React 或 Vue 项目里稍微改两行技术栈描述就能直接用。3.1 前端模板的整体目录结构frontend-template/ ├── CLAUDE.md └── .claude/ ├── commands/ │ ├── code-review.md │ ├── add-test.md │ └── changelog.md ├── skills/ │ └── component-arch.md └── hooks/ └── pre-commit.md每一层都在干自己的事绝不越界。3.2 CLAUDE.md 的内容设计项目根目录的CLAUDE.md是这套模板的心脏。我写的格式不算花哨但信息密度很高。核心结构是这样的# 项目身份卡片 - 项目名称XXX 前端应用 - 技术栈React 18 TypeScript 5 Vite Tailwind - 包管理器pnpm - 测试框架Vitest Testing Library # 目录结构 - src/components —— 纯展示组件 - src/features —— 业务模块每个 feature 自带 hooks、components、api - src/lib —— 通用工具函数 - src/stores —— 全局状态 # 编码规则 - 组件文件使用函数组件 hooks不使用 class 组件 - 样式一律用 Tailwind 类名禁止在 CSS 文件里硬写颜色值 - 所有异步请求必须走 src/lib/request.ts 封装禁止直接调用 fetch - 状态管理优先使用 zustand禁止为了局部状态引入 redux # 交付标准 - 每个功能改动必须附带对应测试 - 测试文件与被测文件放同一目录命名 xxx.test.tsx - 提交信息必须符合 conventional commits 格式例如 - feat: 添加用户头像上传 - fix: 修复列表滚动加载重复请求 - refactor: 重构订单详情页数据流 # 禁止事项 - 不允许使用 any 类型绕过 TS 检查 - 不允许在 useEffect 里写同步业务逻辑 - 不允许直接修改 store 中 state 的深层嵌套字段必须通过 action 更新你可能发现了这份文件里的每条规则都是可执行的不是建议性的。我不写请尽量保持代码整洁这种废话因为 AI 听到这种话等于没听到。我写的是禁止在 CSS 文件里硬写颜色值它就能在生成代码时自动把颜色类名化。3.3 子命令模板的写法再看一个具体的子命令模板。我举个例子code-review.md这个文件放在.claude/commands/下面执行时输入/code-review就会触发这段指令请对当前改动执行代码评审并按以下顺序检查 1. 逻辑正确性是否存在边界条件遗漏或状态更新顺序问题 2. 类型安全是否有 any、类型断言滥用、不必要的非空断言 3. 性能隐患useEffect 依赖项是否合理是否存在重复渲染风险 4. 可维护性命名是否清晰、组件是否拆分过大、是否有重复代码 评审输出格式 - 问题清单按严重程度排序P0 最高 - 每个问题附上文件路径和行号 - 对每个问题给出最小改动建议不要重写整个文件 如果没有发现问题直接输出LGTM。这段模板的核心在于它限定了评审的角度、输出的格式、问题的分级方式。没有这段模板时我让 AI 做 review它经常输出一堆空话比如建议优化代码结构但具体改哪里、怎么改全都不说。有了这个模板它的输出就变得非常可执行。3.4 技能层模板的使用场景技能层的模板跟子命令不同它不光是一段提示词还包含一个完整的执行工作流。我用得比较多的是component-arch.md用于在新建复杂组件时保证架构一致性这个技能模板会要求 Claude Code 先分析组件的数据依赖和交互逻辑然后输出状态管理设计、组件拆分方案、接口定义最后才生成代码。因为我发现如果直接让它写一个订单表单组件它只会写一个单文件组件把所有逻辑堆在一起。但如果先让模板里的流程过一遍它生成的组件拆分合理、接口清晰review 成本低很多。技能层模板的路径约定是项目级技能放在.claude/skills/Claude Code 会自动把技能目录下的 SKILL.md 信息加载进上下文。你可以把使用说明、前置条件、执行步骤、输入输出规范都写在里面。4. 模板内容怎么写才不会被 AI 忽略模板写得好不好直接决定了 AI 遵守规则的概率。我调试了挺长时间总结出了几条硬经验每条都是从踩坑里熬出来的。4.1 命令式句式优于描述性说明AI 对禁止的理解往往不如对替换行为的理解深刻。与其写不要在 useEffect 里发请求不如写把所有数据获取逻辑放在 React Query 的 useQuery 里。前者只是告诉 AI 不能做什么却没说应该做什么它有时候会给你一个更奇怪的替代方案后者给了明确路径AI 会沿着路径执行。我通常用这两条规则来审查自己的模板内容每条规则是否以动词开头如使用调用写入每条规则是否都指向一个可执行的、具体的操作如果哪条规则做不到我就直接删掉因为它大概率不会被执行。4.2 用正反例锁定 AI 的理解这是我觉得最有效的手段。如果你只写提交信息要符合 conventional commits 格式AI 大概率会给你生成一堆鱼龙混杂的格式因为 conventional commits 的细节很多它不知道该按什么标准来。但在模板里加一个反面例子效果立刻不一样提交信息格式要求 - 正确feat: 添加用户头像上传功能 - 正确fix: 修复订单列表在弱网环境下的重复请求 - 错误修复bug - 错误update code有正反例之后AI 在生成提交信息时会自动对照这两个例子格式不符的会被它自己否决掉。这个方法可以应用到任何规则上从命名规范到目录结构只要涉及格式都值得配一个正反例。4.3 控制模板长度把超出篇幅的内容外包CLAUDE.md 文件超过 80 行之后AI 的执行表现会明显下降。我做过对比测试同样是写一个接口请求模块一个项目配置了 40 行的 CLAUDE.md另一个配置了 150 行的在严格遵守代码风格这一项上前者表现更好。原因不复杂。Claude Code 会把 CLAUDE.md 的内容注入到每轮对话上下文中文件太长会占用上下文空间而且关键指令会被埋在大量文本里注意力分配不均。所以长内容要外包比如详细的样式规范如果有一大堆颜色、间距、字体定义不要写进 CLAUDE.md而是放到一个docs/style-rules.md文件里然后在 CLAUDE.md 里加一行生成样式相关代码前先阅读 docs/style-rules.md 并严格遵循。这样既保留了完整规范又不占用 CLAUDE.md 的注意力额度。4.4 模板要常驻而不是一次性会话规则我的一个习惯是在模板文件里安排一个当前进展段落。这个段落会在会话结束时由 AI 自动更新写下当前完成了什么、下一步准备做什么、有哪些遗留问题。下次新开会话时Claude Code 读到这段内容就能无缝衔接上次的工作不用我问上次做到哪了。实现方式也很简单在 CLAUDE.md 末尾加一节# 当前进展 - 上次会话完成时间 - 已完成内容 - 待办事项 - 已知问题然后每天下班前我会让 AI 更新这个文档。这比任何笔记工具都直接因为信息天然就在项目上下文里。5. 版本管理与多项目复用策略模板建好之后最大的问题变成了如何维护和如何复用。一个模板只要维护两三个项目就会开始走样需要建立一套机制来保证它始终可用。5.1 模板仓库本身纳入 Git 管理这套 claude-code-templates 仓库本身就是我用 Git 在维护的。每次改规则都是一次代码提交有历史记录、有 commit message可以回滚。这样做的好处是什么呢就是规则演进有迹可循。我会在 commit message 里写清楚为什么改这条规则。比如有一次我在前端模板里加了一条禁止在组件内直接使用 window.location 跳转原因是 AI 在生成登录逻辑时绕过了路由守卫。这条规则我备注了feat: 阻止 AI 绕过路由守卫直接跳转三个月后我再看到这条规则能立刻想起当时的场景。5.2 项目接入模板的两种方式接入方式是另一个关键决策。我试过两种各有利弊。第一种是拷贝式把模板目录整体复制到新项目里。好处是项目独立不受模板更新影响坏处是模板后续改了项目里不会自动同步时间一长项目里的 CLAUDE.md 就变成了一个没人维护的老旧版本。第二种是软链式把模板文件软链到项目目录里。好处是模板更新后所有项目自动生效坏处是如果你在不同项目里需要不同的规则软链会让你很难做项目级定制。我现在的做法是混合的全局规则和通用命令用软链因为这两个基本不会因项目而变项目专属的 CLAUDE.md 用拷贝然后在拷贝版本里维护项目特有的规则。这样既保持了全局的一致性又留了项目定制的空间。5.3 多项目环境下的目录组织如果你同时维护多个前端项目我建议在模板仓库里按项目类型建子目录而不是按项目名建。也就是说别建一个project-admin-web的子目录而是建一个react-spa-template然后把所有 React 单页应用的通用规则放进去。原因在于通用规则不会因为项目名字不同而改变但如果你按项目建目录等于把同一套规则复制了好几份改了其中一个其他项目的模板还是旧的维护成本飙升。我目前的做法是projects/ ├── react-spa-template/ # 通用 React SPA ├── vue-spa-template/ # 通用 Vue SPA ├── nestjs-service/ # 通用 NestJS 服务 └── python-fastapi/ # 通用 Python FastAPI 服务每个目录下的模板都是经过至少两个真实项目验证的这意味着我把它拷进新项目时里面的规则大概率已经覆盖了大多数坑。5.4 团队协作里的配置同步如果你跟我一样是团队负责人会发现模板还有一个额外价值统一团队的 AI 协作规范。团队里其他成员用自己的 Claude Code 时只要他们拉取了这份模板并通过软链接入他们的 AI 就会自动遵守跟你在项目里完全一致的编码规则。这比让每个成员各自维护一份规则靠谱得多也避免了你的 AI 按 A 风格写代码他的 AI 按 B 风格写代码最后合并代码时一地鸡毛的情况。6. 落地过程中踩过的坑和现在的用法再好的理论放到真实项目里都会遇到各种意外。我把这段时间踩过的坑整理一下希望你不用再走一遍。6.1 坑一模板内容太多导致 AI 注意力稀释这个前面提到了但我还想再强调一次。我第一次建模板时特别兴奋把所有能想到的规范全塞进 CLAUDE.md结果导致 AI 在生成代码时频繁失忆尤其是会话超过三轮之后它经常写出违反早期规则的代码。解决办法是精简。现在我的 CLAUDE.md 始终控制在 60 行以内凡是可以写进代码注释里的东西都不进模板凡是只有在特定场景才用到的规则一律移到对应的子命令或技能里。需要时触发不需要时不占内存。6.2 坑二规则太抽象AI 执行走样一开始我在模板里写了保持代码整洁结果 AI 生成了一堆完全符合语法但极度冗长的代码。后来我把它改成组件超过 150 行必须拆分子组件效果立竿见影。这个坑给我的教训是给 AI 的规则必须是可以被客观衡量的。进度快一点不是规则每个会话结束前输出当前进展才是规则。所以我现在审查模板时每读一条规则就问自己如果我是机器看到这条规则能确定地执行吗不能就改。6.3 坑三hooks 脚本复杂过头反而阻塞开发模板里的自动化层如果配置失误会直接卡住正常操作。我曾经写过一个 pre-commit 钩子要求 AI 在每次提交前自动检查代码格式并修复理论上很美好。但实际上 Claude Code 在跑修复时偶尔会误改不该改的地方然后提交就失败了要人工去 review 改动反而拖慢效率。后来我把钩子改成了只检查并输出违规清单不自动修改。检查结果是纯信息式的不阻断提交流程只是提醒我这里有格式问题要不要处理。这样既不阻塞开发又能保留自动化检查的价值。6.4 坑四技术栈版本写死模板迅速过时模板里写React 18没问题但如果你写了React 版本不得高于 18那等 React 19 发布时这个模板就成了阻碍升级的拦路虎。我现在的表述方式是React 18升级前需评估 breaking changes 并单独提交。既给了版本约束又留了升级路径。6.5 我现在日常是怎么用的最后说说我现在的工作流。新项目开工时我会先把他对应的模板仓库目录拉进去然后跑一个初始化脚本。这个脚本做的事情包括把projects/react-spa-template/CLAUDE.md复制到项目根目录创建.claude/commands/目录并把shared/commands/下的通用命令软链进去把global/CLAUDE.md软链到~/.claude/CLAUDE.md只需要做一次打开刚复制的CLAUDE.md修改项目名称和技术栈描述整个过程大概五分钟。然后新开的会话里Claude Code 已经知道自己在这个项目里该做什么、不该做什么了。我不用再花时间介绍背景直接说开始写订单模块就行。这套模板体系不是一次建完的它是跟着项目一起长的。每次踩坑我就往模板里补一条规则每次发现 AI 反复犯同一个错误我就把应对方案固化进模板每次同事反馈某条规则不好用我就调整表达方式。到现在这套 claude-code-templates 已经变成了我团队里所有 AI 协作的底稿它不需要多智能只需要稳定——稳定地告诉 AI这是我们的规矩照做就行。