Claude Code 模板体系实战：从 CLAUDE.md 到 Slash Commands 与 Agent Skills

先说个我自己的体会用 Claude Code 写了几个月项目之后最让我头疼的不是模型能力不够而是同一个需求反复描述、同一套规范每次重讲、同一个坑换个项目再踩一遍。后来我花了一整周时间把自己常用的工作流、代码规范、审查清单全部沉淀成了一套模板体系也就是标题里这个 claude-code-templates。现在开新项目只需要几条命令Claude 就能按照我习惯的方式直接进入状态。这篇文章不是讲某个现成仓库的安装教程而是分享我如何从零搭建一套可复用的 Claude Code 模板体系包括 CLAUDE.md 的写法、自定义斜杠指令、Agent Skills 的设计思路以及我在实际项目中踩过的坑。适合已经在用 Claude Code、但对“模板化”还没有系统思路的开发者参考。1. 模板体系到底解决什么问题先说结论claude-code-templates 不是某个单一文件而是一整套让 AI 助手在你的项目里稳定发挥的规则和工具组合。它解决的核心问题有三个分别是上下文一致性、Token 成本控制、隐性知识沉淀。1.1 模板体系的三层结构我理解的模板体系包含三层内容从最基础到最灵活依次是CLAUDE.md 记忆文件Claude Code 会在每次会话开始时自动读取项目根目录下的 CLAUDE.md把它当作项目的“说明书”。这里适合放稳定不变的规则比如技术栈约定、目录结构、代码风格、禁止事项。自定义 Slash Commands斜杠指令放在.claude/commands/目录下的 Markdown 文件你可以定义/review、/test、/refactor这类快捷指令。指令内容可以携带参数、引用其他文件适合放那些“经常要用但不想每次手打”的操作流程。Agent Skills技能包Claude Code 后来推出的技能机制本质上是一组 SKILL.md 加配套脚本让模型在需要时主动调用。比如“读取这个项目的部署文档并检查配置”就可以封装成一个技能按需触发。这三层不是替代关系而是配合使用。CLAUDE.md 解决“你是谁、项目是什么”的定位问题Slash Commands 解决“怎么干活”的流程问题Agent Skills 解决“遇到特定场景时自动调用什么知识”的触发问题。1.2 没有模板体系时会遇到什么问题很多人的 Claude Code 用得稀烂不是模型不行而是每次会话都是从零开始。模型没有项目背景、不知道你的代码风格、不了解你上次改到哪里于是你花大量时间在“重复解释”上。我在没有模板体系之前典型场景是这样的让 Claude 改一个前端组件的样式它会自己发挥出一套和项目风格完全不搭的写法让它写测试它默认假设你用的是 Jest而项目里实际是 Vitest让它修一个 bug它找不到关键文件在无关代码里翻半天。这些问题本质上是信息缺失不是能力问题。模板体系就是把你说过的话、写过的规则、踩过的坑提前放进模型的上下文里让它不用问就知道该怎么干活。2. CLAUDE.md 的核心写法与设计思路CLAUDE.md 是整个模板体系的地基。大部分人只是简单写几句话扔进去就完了其实它的结构设计很有讲究。2.1 区块划分按“触发场景”而非“内容类型”组织很多人写 CLAUDE.md 喜欢按“代码规范、架构说明、测试要求”这种内容类型来分区块但我实测下来效果最好的方式是按模型的思考流程来分区块。我现在的 CLAUDE.md 长这样# 项目概览 一句话说清楚这是什么项目、核心业务目标是什么、线上环境地址。 # 命令与工作流 - 开发启动npm run dev - 构建检查npm run build - 测试执行npm run test - 类型检查npx tsc --noEmit # 技术栈与约束 - 框架Vue 3 TypeScript禁止引入 jQuery 等遗留库 - 样式Tailwind CSS禁止写全局 CSS 覆盖 Tailwind 变量 - 状态管理Pinia业务状态必须走 store禁止组件间跨级传参 # 代码风格约定 - 组件文件名PascalCase - 工具函数文件名camelCase - 提交信息遵循 Conventional Commits # 架构与关键目录 - src/modules业务模块每个模块内包含 components、views、api、store - src/shared跨模块复用的公共组件与工具 # 常见任务检查清单 ## 新增页面 1. 在对应模块的 views 下创建组件 2. 在 router 配置中注册路由 3. 确保路由懒加载 ## 修改 API 请求 1. 检查 src/modules/xxx/api 下的接口定义 2. 确保错误处理统一走 errorHandler # 绝对禁止 - 不要修改 src/shared 下的公共组件而不更新使用方 - 不要直接在页面组件里写业务逻辑 - 不要绕过 ESLint 规则提交代码这里的关键是每个区块都对应模型一次可能的思考路径。比如它刚读完项目概览自然会想知道你怎么启动项目于是“命令与工作流”放在紧跟着的位置就很自然。技术栈约束最好放在命令后边因为它接下来会想“我该用什么框架写代码”。2.2 控制文件长度CLAUDE.md 不是越全越好最常见的误区是把 CLAUDE.md 写成一本百科全书动不动就几千行。CLAUDE.md 是每次会话默认读入上下文的太长了既消耗 Token又会让模型抓不住重点。我踩过一次很惨的坑把一个老项目的全部业务规则写进了 CLAUDE.md足足 600 多行结果 Claude 在处理具体任务时频繁引用无关规则甚至出现规则之间的“自我矛盾”——因为有些规则描述得不够准确模型开始纠结字面意思而不是干活。我的经验是单个 CLAUDE.md 控制在 200 行以内超过就该精简或拆分。详细规范类内容放进独立文档比如docs/engineering-practices.md在 CLAUDE.md 里只留一句“详细规则见 docs/engineering-practices.md涉及代码风格时请先阅读该文件”。需要模型在特定任务中调用的长文档用引用方式临时注入而不是默认读入。2.3 全局与项目级的双轨配置Claude Code 支持在~/.claude/CLAUDE.md放全局记忆文件也支持项目根目录放项目级 CLAUDE.md。这两个文件的定位完全不同全局文件放的是你个人的通用偏好比如“回答问题时先给结论再解释原理”“涉及安全敏感操作时必须先说明风险和影响面再动工”。我还在全局文件里写明了自己常用的技术栈偏好省得每个项目写一遍。项目级文件只放这个项目特殊的约束和背景二者不要互相覆盖。我见过有人把全局偏好复制到每个项目里结果两边内容冲突时模型不知道该听谁的表现会非常不稳定。3. 自定义 Slash Commands把重复流程做成指令CLAUDE.md 是静态的而 Slash Commands 是可执行的动作。这是我觉得投入产出比最高的一层因为一条指令就能替代一大段复杂的提示词。3.1 我的第一个指令/review干我们这行的都懂代码审查是个苦力活。以前我让 Claude 审查代码得写一大段话“请审查 src/components/Table.vue 的代码重点关注性能问题、错误处理缺失、是否符合项目代码规范、有没有边界条件遗漏……”现在我在.claude/commands/review.md里写# 代码审查 ## 执行步骤 1. 列出本次修改涉及的文件清单如果用户没有指定具体文件默认审查最近一次 git diff 涉及的文件。 2. 逐一审查文件重点检查 - 性能隐患不必要的渲染、重复计算、大数据量未分页 - 错误处理接口调用是否有失败兜底、文本框是否做了类型校验 - 代码规范是否符合 CLAUDE.md 中的风格约定 - 边界条件空值、超长文本、重复点击 3. 按严重程度分三档输出问题列表阻断、建议、Nice to have 4. 对每个问题给出修改建议尽量直接给代码片段 5. 如果审查结果全部通过明确说“未发现明显问题”不要强行凑建议 ## 输出格式 ### 阻断问题 问题描述、影响面、修改建议 ### 建议优化 问题描述、修改建议 ### 问题统计 共发现 X 个问题其中阻断 X 个、建议 X 个这里我特意在指令里加了“如果审查全部通过不要说废话”这条规则。原因很实际这个模型在没有明确要求时倾向于“找点话说”强行给出几条无伤大雅的优化建议来显得自己有用但实际上你只需要它老老实实汇报事实。3.2 支持参数和引用的指令/commitSlash Commands 支持参数传递这样就能做出更灵活的指令。我以前写 commit message 靠手打现在直接签一个 /commit# 生成提交信息 输入$ARGUMENTS 为需要补充的提交说明 ## 执行步骤 1. 运行 git diff --cached 查看已暂存的改动 2. 分析改动内容提取核心变更点 3. 按 Conventional Commits 规范生成提交信息 4. 提交说明需包含 $ARGUMENTS 中用户提供的补充信息 5. 如果改动涉及破坏性变更必须以 ! 标识并写清说明调用方式是在对话里输入/commit 修复了列表页在移动端的布局错位问题Claude 会结合暂存区改动和你的补充说明生成符合规范的提交信息我确认后直接执行git commit。这个指令还有个隐藏好处因为每次提交前必须看一下暂存区我养成了“不把无关文件混进提交”的习惯。3.3 指令的指令在 Slash Command 里调用其他 Slash CommandClaude Code 的指令文件里支持相互引用这个特性用处很大。我可以做一个/task的总控指令它把任务拆解之后调用/generate、/review、/test等子指令。我的做法是把指令拆成两个层级流程指令比如/feature负责一次完整的功能开发流程它内部定义步骤每个步骤里要求调用对应的子指令。原子指令比如/test专门负责生成测试/doc专门负责写文档。这样做的好处是模型在一段长流程里不会“跑偏”因为每个步骤都有明确的指令约束而不是靠它在上下文里自己理解。我现在开发一个完整功能模块时就直接敲/feature 用户资料修改页它会按我的顺序来先解析需求、生成接口代码、生成页面组件、补齐测试、最后跑一遍 review。4. Agent Skills让模型自己决定什么时候翻细则Slash Commands 是“用户主动触发”Agent Skills 则是“模型在需要时自己主动调用”。这两者场景完全不同但配合起来威力很大。4.1 Skills 的目录结构与 SKILL.md 写法每个 Skill 其实就是一个目录里面至少包含一个SKILL.md文件。Claude Code 会在模型判断“当前任务和这个技能相关”时自动加载它的描述。描述写得越清晰模型越能在正确时机想起来用它。我举一个实际例子我的项目里有大量后端接口联调最烦的是接口字段命名不统一。后来我写了一个api-naming-consistency技能--- name: api-naming-consistency description: 当用户要求新增、修改或调试 API 接口时自动检查接口命名是否符合后端接口命名规范。适用于涉及 fetch/axios 调用的任务。 --- # 接口命名一致性检查 ## 触发场景 - 用户要求新增接口时 - 用户要求修改请求参数、响应字段时 - 用户要求调试接口联调问题时 ## 检查规则 1. 请求路径统一使用 kebab-case避免 snake_case 和 camelCase 混用 2. 请求体字段使用 camelCase但需要映射为后端要求的 snake_case 字段名 3. 响应处理统一封装不要直接在业务组件里写 res.data.xxx 这种硬编码 4. 错误响应必须统一走 errorHandler 处理禁止在业务代码里到处 catch每次涉及接口相关任务时这个技能会自动被模型加载它就会照着检查一遍代码。这个体验和 CLAUDE.md 完全不同——CLAUDE.md 是强制常驻上下文而技能是按需加载既不会浪费 Token又能在关键场景兜底。4.2 Skills 与 CLAUDE.md 的分工策略我个人的实践分配是CLAUDE.md 里只写“绝对不能碰的底线规则”和“最常用的命令”这些属于高频且稳定的信息。Skills 里放的是“特定任务才需要的中频率规则”比如接口命名、测试写法、部署流程、日志规范。这样分配的好处是有的我举个例子就明白了CLAUDE.md 里我写“禁止在业务组件中硬编码请求逻辑”这样一句就够了而具体的接口字段命名规则、错误处理细节都放进 api 技能里。假设一个会话完全没碰接口相关内容模型根本不需要加载那些细节一旦要写接口技能就自动顶上。4.3 一个技能里包含可执行脚本Skills 不只是文本规则它还能带脚本。Claude Code 的 skill 目录中可以包含可执行脚本模型在执行该技能时会自动运行这些脚本来辅助判断。我做过一个比较实用的技能build-check。在 SKILL.md 里规定“当用户提交代码前确认项目能通过构建检查”同时带了一个 Bash 脚本自动跑npm run build然后把报错信息带回到对话里。这样模型说“可以提交”之前是真的跑过构建的而不是拍脑袋。这个做法颠覆了我对“AI 助手”的认知它不再只是在文本层面给建议而是能直接操作终端里的命令。你把规则写清楚它能像一个认真的工程师那样先验证再断言。5. 实操全流程从零搭建一套模板理论说了这么多下面是我在新项目里完整的搭建流程可以照着抄。5.1 初始化项目级 CLAUDE.md新项目克隆下来之后我先花 30 分钟写项目级 CLAUDE.md。不要偷懒模板的根基就在这个文件里。具体写法建议分四步走第一步写项目概览。这个项目做什么的、主要用户是谁、核心业务链路是什么尽量用两到三句话说清楚。模型理解了这个后续代码生成才有方向感。第二步写本地开发命令。包括启动、测试、构建、类型检查、lint 这五类命令版本锁在 package.json 里。第三步写技术栈约束和目录结构。明确框架版本、状态管理方案、组件库、样式方案以及每个目录的职责边界。这一条是防止模型乱放文件的关键。第四步写任务检查清单。把项目里最常做的几类任务新增页面、新增接口、修改公共组件、发版的步骤写清楚模型会照做而且完成质量会明显稳定。5.2 设计第一批 Slash CommandsCLAUDE.md 写完接下来配置指令。我推荐第一批只配四个指令覆盖最高频场景/review代码审查/commit生成提交信息/test为指定模块补测试/refactor按给定方向重构代码这四个指令覆盖了我日常 80% 的重复劳动。配完之后每个项目里复制同名指令文件进来即可里面的措辞可以统一不用每个项目重新写一遍。如果你发现某个流程比如“发布预览环境”“生成 API 文档”连续用了三次以上就应该考虑把它固化成一个指令了。5.3 项目级技能先从一个痛点开始Skills 的设计思路是“从痛点反推”。我搭建技能时会选择当前项目中最容易出问题的环节来写如果这个项目接口字段经常对不上就写接口一致性技能如果部署流程繁复就写部署检查技能如果测试覆盖率老是不达标就写测试补全技能。关键是不要贪多。在没想清楚之前一个项目里挂七八个技能反而会让模型在选择时犹豫不决。我建议从最痛的一个点开始跑通之后再逐步加。5.4 模板生效的验证方法写完这些之后怎么验证模板真的有效最好的方法就是开一个全新的会话输入一个真实任务然后观察模型是否能主动使用模板中的信息。我常用的验证文案是“请按本项目的规范在 src/modules/user 下新增一个用户列表页包含列表查询、状态筛选、分页功能并补上测试。”然后观察它是否读取了 CLAUDE.md 中目录结构的描述它是否按照命令里定义的测试规则来写测试它是否遵循了组件命名和样式方案如果它有某一处违反了模板里的规则我就回去检查对应模板文件的措辞是否足够明确。模板本身也是一段“代码”需要调试和迭代。6. 常见问题与排查技巧实录最后这部分是我在使用模板过程中真实遇到过的坑每一个都花了功夫才解决。6.1 模板写了但模型不遵守这是反馈最多的一个问题。排查思路是先分清是“没读”还是“读了没执行”。验证方法很简单直接问模型一句“项目里定义的代码风格约定是什么”。如果它答不上来或答偏了说明 CLAUDE.md 没有正确加载检查文件位置是否在项目根目录、文件名是否为 CLAUDE.md如果它答对了但实际没照做那问题出在“措辞不够强硬”把“建议”“应该”这类词改成“必须”“禁止”效果立竿见影。还有一种情况是 CLAUDE.md 与其他指令内容冲突。比如 CLAUDE.md 里说测试用 Vitest但某个 Slash Command 里写的是 Jest模型会倾向于执行指令里的内容。出现这种情况不要犹豫删掉冲突那一侧保持全库一致。6.2 指令太长导致执行不完整Slash Command 文件如果太长超过 100 行模型执行到后半段时会出现“忘记前面步骤”的情况尤其是多步骤流程。我的对策是进行拆分总控指令只写步骤框架每步不超过三句话细节步骤放到对应子指令文件里总控里用一行“执行 /xxx 指令”来引用这就像写代码一样函数体太长就该拆函数。指令文件也一样保持每个文件的职责单一。6.3 多项目模板复制后的维护难题模板做得顺手之后各个项目里复制粘贴同一套文件很快会出现“同一份规则在不同项目里有几个版本”的问题。我目前的解法是维护一个公开模板仓库就是 claude-code-templates 这个项目的雏形把通用指令和通用技能放在里面。新项目用code命令拉取一套基础模板进来再根据项目特点做增量修改。注意复制过来的模板一定要过一遍删掉项目和项目之间不同的部分比如某个技能引用的是另一个项目的目录结构不改的话会带偏模型。6.4 模板把模型“带跑偏”模板写得太细有时候也会造成问题。最典型的是我一开始把“用户体验偏好”写进了 CLAUDE.md比如“按钮文案不要体现极客风”“风格偏传统”结果模型在生成代码时会过度关注文案措辞对逻辑正确性关注反而下降。经验是模板里只放客观规则技术栈、架构、流程、禁止事项不要放主观偏好。主观偏好你可以通过对话临时告知而客观规则才是需要常驻的硬约束。6.5 团队协作时模板冲突如果团队里多人共同维护一个项目每个人往 CLAUDE.md 里加几条自己的规则文件会迅速膨胀到失控。我现在的做法是在项目根目录只放最基础的约定团队其他细则统一放在“团队共享模板库”里用自动化脚本按时同步到各成员机器上避免人工拷贝。还有一个容易被忽略的细节项目里的 CLAUDE.md 如果频繁变动会直接影响模型的上下文稳定性。因为每次内容一变同一段任务在不同会话里的表现就可能不一致。所以模板修改要批量、有计划地改动别今天改一行、明天删一行。7. 模板库的持续演进最后聊一下我对模板体系未来演进方向的理解。从实践来看模板体系不是写一次就完事的静态产物而是会随项目演化的动态资产。我现在基本每个月会对模板库做一次回顾哪些指令的调用频率变低了哪些技能描述和实际行为有偏差哪些规则该从技能提升到 CLAUDE.md 常驻层。一个重要原则是指令描述的语言要像代码一样有版本意识。改了某个指令但没测试就直接放进正式项目很容易出现模型行为与实际预期不符的情况。我习惯每次改模板之后在测试项目里先跑一轮验证对话确认无误再同步到正式项目。另一个趋势是模板的组合使用一套基础模板负责通用能力代码生成、审查、测试、提交每个项目叠加项目专属模板目录规范、接口约定、部署流程。这样既能保证多项目之间的体验一致性又能保留每个项目的特殊性。根据我个人的实操经验一个好的模板体系要做到“静若处子、动若脱兔”平时不打扰模型的核心推理但一旦进入特定场景该触发的规则必须立刻生效。这需要你对 Claude Code 的能力边界有清晰认知也需要你自己对工程流程有深入理解二者缺一不可。别指望一个模板文件解决所有问题真正值钱的是你把自己的工作流程吃透之后把它翻译成模型能执行的语言的过程。