Claude Code模板化配置全指南：从CLAUDE.md到子代理与技能

我大概是去年年初开始重度使用 Claude Code 的当时还是一个纯手动喂 prompt 的状态每次开新项目都要把技术栈、目录结构、编码规范重新讲一遍每轮代码评审也得重新粘贴一遍检查清单。直到我在社区里看到有人把自己的 .claude 目录整个打包分享才意识到这个工具最被低估的部分根本不是对话而是 templates——模板化配置。说直白点Claude Code 的 templates 就是把“你希望 AI 怎么帮你干活”这件事沉淀成文件。它包含 CLAUDE.md 记忆文件、斜杠命令、子代理 Agent、技能 Skills以及对应的目录规范和版本管理策略。这套东西搭好之后AI 从一个每次都要重新调教的聊天对象变成一个带着完整工作手册进场的协作者。这篇文章我把自己从零搭建到迁移到团队协作全过程的模板体系、踩坑记录和配置细节完整写出来适合刚开始接触 Claude Code想让它在团队里落地、或者正在被“AI 每次记不住上下文”折磨的人。1. 先搞清楚模板到底管的是哪几层很多人一上来就复制别人现成的 CLAUDE.md结果发现不是不好用而是根本不对路。原因很简单模板体系不是单一文件而是分层的。你没有先理解每一层的作用边界抄来的东西就像穿了不合身的西装哪哪都别扭。1.1 模板体系的四层结构我自己把 Claude Code 的模板体系分成四个层级记忆层、指令层、角色层、技能层。记忆层就是 CLAUDE.md它负责让 Claude 知道“你的项目是什么、有什么约束”。指令层是自定义斜杠命令把“帮我跑测试”“帮我做 code review”这类高频动作做成固定入口。角色层是 subagents也就是子代理让 Claude 在复杂任务中分化出“架构师”“测试员”“文档工程师”这些专职角色。技能层则是更大粒度的能力封装比如“完整的重构流程”或“从零搭一个新模块”它可以横跨多文件、多步骤。这四个层级我目前用的频率占比大概是这样的CLAUDE.md 几乎每次会话都在被加载斜杠命令每天会用十几次subagents 和 skills 则是在特定场景下按需调用。实际使用中很多人上来就折腾 subagents 和 skills结果连最基础的 CLAUDE.md 都没写好这是本末倒置。1.2 为什么模板化比“每次现聊”效率高最直观的收益是上下文一致性。不写模板的时候你每个新会话都要重新培养 Claude它开局对你的技术栈理解是零。而模板相当于给它的“入职培训”一进场就知道项目用 React 还是 Vue、测试框架是 Jest 还是 Vitest、代码里有哪些历史包袱不能碰。第二层收益是团队行为对齐。团队里十个人用同一个模板仓库那么十个人的 AI 行为基线是一致的。以前代码风格靠 code review 一个个人盯现在 AI 在生成时就会按照模板里的规范约束自己相当于把 review 的压力前置了。第三层收益是沉淀经验。模板本质上是你写过的所有 prompt 里面最精华、最通用、最少踩坑的那部分的结晶。它从一次性消费变成了可复用的资产这个价值是巨大的。2. CLAUDE.md整个模板体系的“地基文件”CLAUDE.md 是 Claude Code 的记忆机制会在每次会话启动时自动加载。它的优先级和加载机制有明确规则这个搞不懂后面全白搭。2.1 用户级与项目级的加载优先级CLAUDE.md 支持四个位置在 ~/.claude/CLAUDE.md、~/.claude/CLAUDE.local.md、项目根目录的 CLAUDE.md、以及项目内的 CLAUDE.local.md。前两个是用户级后两个是项目级。加载顺序是项目根目录优先于用户级。更确切地说Claude 会合并读取这些文件但在冲突时项目级配置会覆盖用户级配置。这个设计很合理用户级放的是你个人通用的偏好比如“代码注释用中文写”“不要使用 console.log 调试”项目级放的是项目专属约束比如“本项目禁止使用 Redux统一用 Zustand”。我当时踩过一个坑在一台新电脑上想把用户级的 CLAUDE.md 直接复制成项目级结果导致项目里出现了很多我个人的编码偏好被队友吐槽了。后来我定了一个原则用户级只放 100% 通用的行为偏好项目级才放与项目强相关的约束两者尽量不重叠。2.2 CLAUDE.md 的内容结构骨架一份好用的 CLAUDE.md我的经验是控制在 60~120 行不要写成百科全书。超过这个量Claude 的注意力反而会被稀释记不住重点。我常用的结构模板如下# 项目角色定位 你是一个资深前端工程师负责维护一个基于 React TypeScript 的中后台管理系统。 # 技术栈约束 - 框架React 18 Vite TypeScript禁止引入 Next.js - 状态管理Zustand 统一禁止 Redux - 样式方案Tailwind CSS CSS Modules 混合禁止使用 styled-components - 测试Vitest React Testing Library禁止使用 Jest # 编码规范 - 所有组件使用函数式组件 Hooks禁止使用 class 组件 - 文件命名组件使用 PascalCase工具函数使用 camelCase - 导入顺序React → 第三方库 → 本地组件 → 本地工具函数 → 样式文件 # 常用命令 - 启动开发服务器pnpm dev - 运行测试pnpm test -- --watch - 构建生产包pnpm build # 禁止事项 - 不要在没有确认的情况下删除任何看起来没用的代码 - 不要修改公共组件库中的组件除非明确说明 - 不要在业务代码中创建新的枚举类型 # 项目结构说明 - src/components公共组件 - src/pages页面级组件 - src/storesZustand store 定义 - src/utils工具函数写的时候有几个细节不要用“请帮我看一下这个组件的逻辑有没有问题”这种开放式描述而是用“使用命令pnpm test -- --watch验证修改是否影响现有测试”这种带明确动作的句子。Claude 是一个大语言模型指令越具体它的合规率越高。我试过在 CLAUDE.md 里写“保持代码整洁”结果它理解不了什么叫“整洁”。改成“不允许出现超过 200 行的函数超过则拆分成多个函数”之后效果立竿见影。抽象词汇在模板里越少越好具体阈值和规则越多越好。2.3 维护 CLAUDE.md 的版本意识很多人的 CLAUDE.md 是一潭死水写完之后就再也不动了。我的建议是每次在 code review 中发现自己反复强调同一类问题就把这个问题转化为一条模板规则。比如我在某项目接连两次发现 AI 生成的代码都没处理接口超时就在 CLAUDE.md 里加了一条“所有 API 调用必须包含超时处理建议使用 AbortController 或 Axios 的 timeout 配置”。加了之后这个问题出现的频率几乎降到了零。另外CLAUDE.md 也是要写 changelog 的。我一般在文件头部用注释块记录最近一次修改的日期和内容方便后续追溯。这个习惯在多人协作时特别有用不然你都不知道队友把哪条规则删了删了之后 AI 行为变了却不自知。3. 自定义斜杠命令把高频动作做成“快捷键”斜杠命令是 Claude Code 里最容易被忽略、但投入产出比最高的功能。它的核心逻辑是把一段精心设计的 prompt 存成文件然后通过/命令名触发Claude 会把文件内容注入到当前对话中执行。3.1 命令文件的存放路径与格式规范自定义命令放在项目的.claude/commands/目录下每个文件对应一个命令文件名就是命令名扩展名为.md。用户级的命令放在~/.claude/commands/下对所有项目生效。命令文件的开头是可选的前置元数据称为 Frontmatter用来控制命令的展示信息下面是命令正文。我举个例子一个 code review 命令的完整实现--- description: 对指定文件或当前改动做全面代码审查 argument-hint: [文件路径或留空] allowed-tools: Read, Grep, Glob, Bash --- 你是项目中的资深代码审查者请基于 CLAUDE.md 中的编码规范对当前 git 改动或指定文件进行全面审查。 审查必须覆盖以下维度 1. 逻辑正确性有无明显 bug、边界条件是否处理 2. 性能问题有无不必要的重复计算、能否利用缓存 3. 可读性命名是否清晰、函数是否过长 4. 测试覆盖关键逻辑是否缺少对应测试 输出格式 - 按严重程度分严重问题、建议优化、小问题 - 每个问题都必须标注对应的文件路径和行号 - 给出修改建议但不直接修改代码这个命令我用下来最舒服的一点是它给了 Claude 明确的“allowed-tools”限制了它只能读文件、搜索、执行命令但不会动手改代码。审查和修改的职责分离避免它一边 review 一边顺手改了文件。3.2 高频的五个命令模板分享我目前用得最多的五个命令是/review变更审查、/test针对某个模块跑测试并修 bug、/commit生成符合规范的提交信息、/refactor按指定方向重构、/explain解释一段代码的逻辑。/commit命令其实很简单但是它节省的时间是最多的。它会把 git diff 拉出来然后按照 Conventional Commits 规范生成提交信息同时要求必须引用对应的 issue 编号。以前写提交信息全靠手打现在是一个固定格式的模板在驱动对项目的 commit 历史整洁度帮助很大。/test命令是另一个高频入口。它的典型场景是我改完一个组件想让 Claude 针对这个组件跑一遍相关测试如果测试挂了就自动分析原因并修复。这个命令的 prompt 里必须强调“修复失败测试时不要通过删除测试来解决问题”不然它有时候会聪明反被聪明误直接把测试删了来换取绿灯。3.3 命令与 Claude Code 内置能力的配合斜杠命令不是孤立工作的它可以调用 Claude Code 的内置工具例如文件读取、代码搜索、Bash 执行等。在命令文件里通过allowed-tools控制它能用什么这是一个安全边界设计。比如/test命令我允许它执行pnpm test相关的 Bash 命令/review命令我允许它读文件和搜索符号/explain命令我只让它读文件。限定得越严格出格的概率越小。另一个很重要的点是斜杠命令可以在正文里引用变量。Claude Code 支持其中一部分动态参数比如$ARGUMENTS用来接收用户在命令后输入的参数$1、$2取前面的参数还支持!file语法把文件内容作为参数扩展。这个功能特别适合那种需要在命令里传文件路径的场景比如写一个/check [文件名]命令来检查单个文件的规范。4. 子代理 Agent 和技能模板的“进阶形态”当你把 CLAUDE.md 和斜杠命令用熟了就应该把注意力放到 subagents 和 skills 上。它们解决的问题是同一个让 AI 拥有不同的“人格”和“工作流”。4.1 子代理 Subagents专职分工的虚拟成员Subagent 本质上是一个被定义好角色、工具权限和行为模式的“子 Claude”。你在 .claude/agents/ 目录下放一个 md 文件就相当于创建了一个虚拟的专职成员。举个例子我在项目中定义了一个“前端架构师”子代理--- name: frontend-architect description: 负责评估前端架构方案、组件设计合理性、依赖选型 tools: Read, Grep, Glob, Bash model: claude-sonnet-4-20250514 --- 你是一位资深前端架构师擅长分布式系统设计、性能优化和大型前端应用的模块划分。 当前项目的关键约束请查阅 CLAUDE.md。 你的职责边界 - 只做架构层面的分析和方案设计不直接写业务代码 - 评估依赖时优先考虑社区维护活跃度、bundle 体积影响、TS 类型完善程度 - 输出结论必须包含方案对比表格、推荐方案、实施步骤这个文件里最关键的是model字段。我可以在模板层面指定某个代理使用更强的模型也可以指定使用更便宜的模型。比如“测试执行”子代理我用快速廉价的模型“架构评估”子代理用高推理能力的模型。模板最大的价值之一就是让模型选型也标准化了。Subagent 与斜杠命令的最大区别斜杠命令是一次性的 prompt 注入subagent 则是一个可以持续对话的“虚拟角色”。你可以先让 frontend-architect 子代理分析方案然后在对话中继续追问细节它会持续以架构师的身份和你的提示词风格进行回应。4.2 Skills 技能可复用的多步骤流程封装Skills 比 subagent 更“重”它是一整套技能的完整定义通常包含描述文件和一个或多个脚本/步骤。Claude Code 的 Skills 标准目录结构是.claude/skills/skill-name/SKILL.md里面用 YAML Frontmatter 定义技能名称、描述然后用 markdown 正文描述执行流程。我举一个“接入新后端 API”的 skill 示例。流程是读取 API 文档 → 生成 TypeScript 类型声明 → 创建 API 请求函数包含错误处理和超时→ 创建 mock 数据 → 生成对应的测试用例。如果没有 skill这个流程每次至少半小时而且很容易漏掉 mock 数据这一步。有了 skillClaude 会按流程执行并且每一步都会给出明确的产出物。Skills 的适用场景是那些流程稳定但步骤较多的重复性工作。判断标准很简单如果这件事你已经重复做了三次以上流程都差不多那就值得封装成 skill。如果每次都不同说明它还不适合模板化硬封装会带来僵化。4.3 子代理、技能、记忆文件之间的关系这三者经常被搞混我用一句话总结CLAUDE.md 是地图subagent 是专家skill 是流程。地图告诉 AI 项目长什么样专家提供领域内的判断力流程则把“怎么做”的步骤标准化。三者互相引用但没有隶属关系。我在实践中通常这样编排CLAUDE.md 中声明“遇到架构问题请咨询 frontend-architect 子代理”subagent 的定义里声明“在分析时可以参考项目里的架构决策记录”skill 则在执行到某一步时让 Claude 调用对应的子代理。这种编排方式能组合出非常复杂但依然可控的工作流。5. 从零到一在真实项目中搭一套模板的完整过程前面讲了很多关于“文件结构”的内容现在来看一下把这些东西组装起来的过程。我用一个实际项目来说明目标是从零构建一套可复用的模板体系。5.1 先做审计再动笔写第一步不是写文件而是盘点你手头项目的关键约束。我一般会列一份检查清单技术栈是什么包管理器是什么测试框架和命令是什么代码风格有没有 ESLint/Prettier 配置有没有项目特有的目录结构团队有没有约定俗成的命名规范CI/CD 流程是怎样的。这些信息不需要全部写进 CLAUDE.md。我的判断标准是哪些信息如果 AI 不知道就会大概率生成不符合预期的代码技术栈和目录结构必须写ESLint 配置这种已经存在于项目文件里的就不用重复写Claude 自己会读取。这个审计过程大概花 30 分钟但能省下后面无数个“它怎么又用了 Redux”的时刻。5.2 分层创建模板目录我推荐按以下目录树来组织.claude/ ├── CLAUDE.md # 项目级记忆文件 ├── commands/ │ ├── review.md │ ├── test.md │ ├── commit.md │ ├── refactor.md │ └── explain.md ├── agents/ │ ├── frontend-architect.md │ └── test-qa.md └── skills/ └── add-new-api/ └── SKILL.md在这个结构里命令文件全部放在 commands 目录subagent 放在 agents 目录skill 则是一个独立的子目录。这样项目管理起来很清楚队友看目录结构就知道能干什么。创建顺序建议是CLAUDE.md 先行然后用三个最常用的斜杠命令review、test、commit跑起来观察几天再逐步添加 subagent 和 skill。不要一次性建太多文件AI 的上下文会被稀释你也不知道哪些规则真的有效。小步快跑、按需添加是我在多次项目中验证过的最稳策略。5.3 实测验证模板是否生效搭建完之后验证模板生效的方式很简单开一个新的 Claude Code 会话问它“我们这个项目的技术栈是什么测试命令是什么”如果它答不上来或者答错了说明 CLAUDE.md 没有被正确加载。再试一下/review命令让它 review 一个已知有问题的文件看它是否按照模板里的审查维度输出结果。我还会做一个更高级的验证故意在一个新会话里问一个与项目规范冲突的问题比如“这个项目能不能用 Jest 替换 Vitest”正常的话它会基于 CLAUDE.md 里的“禁止使用 Jest”规则给出拒绝或警告。这个测试能直观地检验模板的约束力。5.4 版本管理与团队共享的实操模板文件本质上是文本天然适合用 Git 管理。我建议在项目仓库里单独建一个.claude/目录纳入版本控制同时配置.gitignore忽略掉CLAUDE.local.md因为 local 版本是给个人用的不应该跟着仓库跑。团队共享还有一个问题CLAUDE.md 的修改需要走 code review 流程。这不是普通文档它是影响所有人生成结果和行为基线的重要配置。改动之前要在 PR 描述里说明原因比如“新增 API 调用必须带错误处理因为我们最近连续两个 PR 在这上面踩坑”。如果有多个项目共用一套类似的模板建议做一个“模板模板仓库”——就是从这个项目把通用部分抽取出来形成一个claude-templates-starter类的 repo然后每个项目 fork 一份再按项目特点修改。这样既保证全局规范统一又保留了项目定制的灵活性。6. 常见问题与排查技巧实录模板用久了必然会遇到各种问题。我把实际遇到的和社群朋友反馈的高频问题整理成一份速查表每个问题都附上我验证过有效的排查思路。6.1 CLAUDE.md 没生效或者行为不稳这是最常见的困惑。先确认文件的路径是不是项目根目录或 ~/.claude/ 下再检查是否有多个 CLAUDE.md项目级会覆盖用户级这个优先级容易踩还要看是否开了多个会话旧会话的上下文不会自动更新新加的规则需要新开会话。有一个容易被忽略的细节在 CLAUDE.md 里写了规则但规则本身的表述太模糊。比如“注意代码可维护性”AI 永远不知道怎么做。需要把规则具体到“拆分超过 300 行的函数”。如果表述已经具体但效果仍不稳定可以考虑把规则改成更强的措辞比如“必须”“禁止”而不是“建议”。6.2 斜杠命令不出现或执行效果不对命令文件在项目的 .claude/commands 下会自动出现在斜杠菜单中。如果没有出现大概率是路径写错了或者文件名包含特殊字符。另外命令的 Frontmatter 格式要严格写对特别是description字段不能省它决定了命令在菜单里的展示文本。执行效果不对往往是 prompt 本身的问题而不是框架的问题。我调试命令的常用方法把命令正文打印出来直接粘贴到普通对话里看看 Claude 的响应是否符合预期。如果直接对话都回答得不好那就要改命令正文如果对话效果好但命令里差那就是 Frontmatter 的allowed-tools权限给窄了限制了它调工具。6.3 多个 agent 之间的上下文污染不同 subagent 之间如果共用了某些工具或文件可能会遇到上下文互相影响的问题。最常见的是测试 agent 和架构 agent 同时访问同一个目录其中一方进行的修改会影响另一方的判断。我的解法是在 subagent 的定义里通过tools字段严格限定它可以访问的文件范围。比如测试 agent 只允许读src/和tests/架构 agent 只允许读src/和文档目录。必要时还可以在引入上下文时明确要求“忽略其他 agent 生成的文件”。上下文隔离是 subagent 设计里一个非常关键的细节。6.4 模板臃肿后的维护代价模板文件会随着时间增长这是一个真实存在的问题。我的经验是两个判断如果 CLAUDE.md 超过 200 行必须开始精简如果一个命令文档超过 100 行说明它承担了太多责任应该拆成两个命令。另外模板的注释也很重要。我建议在模板文件里注明这条规则的背景来源比如“因为 2024.05 那次线上事故我们统一所有接口请求加入最多重试一次的逻辑”。没有背景的规则后人不知道怎么改也不敢删。有了背景后续维护者能评估这条规则是否仍然成立整个模板体系的维护成本就小很多。6.5 模板文件的安全边界这个点非常重要。让 AI 执行 Bash 命令等于授予它在本地环境的代码执行能力如果模板文件里写了不受限的 Bash 调用风险极大。我给所有模板定了一条铁律永远不要在模板中请求 Claude 执行没有明确限定范围的高危命令比如强制安装全局依赖、直接删除 node_modules、不经确认就执行 git push --force。同时在团队共享模板时要把allowed-tools的字段逐个审一遍。我见过有人在模板里直接给了 Bash 和 Glob结果 Claude 顺手就把整个项目目录的文件列表打出来了这种权限溢出虽然不致命但也很浪费更重要的是影响了它聚焦在当前任务上。我在实际使用中发现模板体系的精华不在于单条 prompt 写得有多漂亮而在于它把 AI 的使用经验沉淀成了团队级别的资产。我自己现在维护了三个项目各自的 .claude 目录之间共享的规则已经抽离成了公共模板库。踩过几次坑之后最深的体会是模板不是一蹴而就的它会随着你的项目一起演化。一开始只需要 CLAUDE.md 加两三个斜杠命令就足够等发现问题后再逐步加规则、再加 subagent、再加 skill。每次新增规则都要问自己一句这真的是反复出现的问题还是偶然的一次如果只是偶然就不值得写进模板。最后再分享一个小技巧每隔一两个月我会把 .claude 目录整体做一次 review专门删掉那些已经失效或者被新规则覆盖的旧条目。模板和代码一样不做定期清理最终会变成无人敢动的遗留代码。