Claude Code模板体系实战：CLAUDE.md、斜杠命令与子代理配置指南

自从把 Claude Code 接进日常开发流程我就一直面临同一个烦恼在不同项目里干活时总要反复用几乎一样的措辞去交代技术栈、说明代码规范、要求输出格式稍微漏交代一句AI 给出的东西质量就明显打折。后来我把这些反复使用的提示词全部抽出来做成了 claude-code-templates 这套模板库——把 CLAUDE.md、斜杠命令、子代理定义全部收拢成项目可复用的配置模板。这篇文章不绕弯子直接讲落地模板体系怎么设计、每个文件该写什么、真正跑起来之后有哪些坑。适合已经开始重度使用 Claude Code、想让 AI 产出质量稳定下来的开发者也适合刚准备入坑、想少走弯路的新手。你照着做大概率能省下每天反复叮嘱 AI 的那十几分钟。1. 项目概述Claude Code 模板的本质与价值1.1 模板到底在解决什么问题Claude Code 本质上是一个无状态的终端 AI 编程助手。每次会话开始它对项目的了解几乎为零。你给它的每一条指令它都要重新理解项目背景、技术栈、代码风格、构建命令然后才能开始干活。这正是问题的根源上下文不稳定。同一段代码你上午让它审查它给你六个方向的建议下午再问一次它只挑了语法问题。你可能觉得是模型智商不稳定其实是你没有给它一套稳定的项目说明书。模板的意义就在这里——把那些你不想重复说的话固化成文件让它每次都能自动读取。CLAUDE.md 相当于给 AI 的一份入职手册讲清楚项目的做事方式斜杠命令则像高频场景的批量指令输入/review就触发一整套审查流程。用生活化的比喻过去你每次找同事帮忙都要从头介绍项目背景现在你直接甩给他一本 SOP他照着执行就行质量自然稳定。另外一个长期被忽视的价值是团队一致性。多个开发者各自跟 AI 对话有人让它输出严格的分级问题清单有人只说一句帮我看看代码。结果就是十个人用 Claude Code十种风格。模板一旦纳入 Git 仓库团队就有了统一的 AI 协作协议新成员也不用靠口口相传记住规范。1.2 这套模板体系适合谁、用在哪先说适合谁。最典型的是重度使用 AI 编程助手的个人开发者他们通常有一整套自己习惯的代码风格和工程规范模板就是这些规范的实体化。其次是中小型团队尤其是远程协作居多、靠 PR review 保证质量的团队。模板把规则前置到了 AI 这里减少了大量人工 review 时的噪音讨论。再说场景。我实际用下来最高频、收益最明显的几个场景是代码审查用统一标准替代个人主观判断、测试用例生成让 AI 主动覆盖边界和失败路径而不是只写 happy path、提交信息生成把 Conventional Commits 规范直接内置、技术方案设计让 AI 先分析约束再给方案而不是直接甩出一段代码。后面我会逐个展开。这套方法不绑定语言或框架你在 Node.js、Python、Go 项目里都可以用差别只在 CLAUDE.md 里写什么内容而已。2. 模板体系的整体架构三层指令结构2.1 第一层CLAUDE.md——让 AI 长期记住项目CLAUDE.md 是 Claude Code 的项目记忆文件放在项目根目录每次会话启动时自动加载。它默认被读取不需要你额外做什么。这个文件的核心作用是让 AI 在对话之前就了解你的工程上下文。我强烈建议在里面固定写这几类内容技术栈摘要、常用命令安装、构建、测试、代码风格约定、项目特有的红线比如禁止什么操作、以及目录结构说明。举个例子我的一个 Vue 3 项目的 CLAUDE.md 写出来是这样的# 项目指令文档 ## 技术栈 - 前端Vue 3 TypeScript Vite - 状态管理Pinia - 样式Tailwind CSS ## 常用命令 - 安装依赖pnpm install - 启动开发pnpm dev - 运行测试pnpm test - 构建产物pnpm build ## 代码风格约定 - 组件文件名使用 PascalCase - 所有 API 请求必须走统一封装的 request 函数 - 修改共享类型时必须同步检查所有引用方 - 禁止在业务代码中直接使用 console.log统一使用 logger ## 项目警告 - 目录采用 feature-based 组织新代码优先放入对应 feature 目录 - 服务端返回时间为 UTC前端展示前必须转换为本地时间 - 涉及第三方 SDK 的改动必须同步更新类型声明写完后你会发现一个很直观的变化让 AI 建议开发命令时它不再猜 npm run serve而会直接给出正确的pnpm dev让它改代码时它也会记得不用 console.log。这个文件就是模板体系的根基其他所有模板都建立在它之上。除了项目根目录Claude Code 还支持用户级全局 CLAUDE.md放在用户主目录下的~/.claude/CLAUDE.md。全局的适合放你跨项目都通用的偏好比如所有回复请使用 Markdown 输出涉及测试代码时优先使用 pytest项目级的负责覆盖具体项目差异。两层会合并生效项目级的内容拥有更高优先级。2.2 第二层斜杠命令——按需调用的任务模板CLAUDE.md 解决的是让 AI 知道背景但背景信息再多也不等于 AI 能把具体任务执行好。比如代码审查你会希望它按固定的几个维度去检查、按固定格式输出。这时候就要用到斜杠命令也就是 Claude Code 的自定义命令功能。斜杠命令的原理很简单在项目的.claude/commands/目录里放一个 markdown 文件文件名就是命令名。比如建一个review.md终端里输入/review这个文件的内容就会作为指令加载。文件开头可以用 YAML frontmatter 写描述方便在命令列表里展示。--- description: 对当前改动进行代码审查按严重程度输出问题清单 --- 请对当前工作区中的未提交改动执行代码审查。检查内容包括 ...我个人使用下来斜杠命令是整套模板体系里提升效率最明显的一层。因为日常开发中真正高频的任务高度集中审查、补测、写提交信息、生成接口文档。把这几个场景做成命令原本每次要敲一两段甚至更长的话现在只需要/review三个字符就搞定而且每次的审查维度和输出格式几乎一致review 质量肉眼可见地稳定。2.3 第三层子代理——值得尝试的角色化玩法子代理是 Claude Code 里更进阶的一种模板机制。你可以在.claude/agents/目录下定义独立的 markdown 文件每个文件就是一个角色有自己独立的系统提示词。和斜杠命令最大的区别是子代理相当于一个专家分身它不只是一个指令模板而是一个有独立人格和能力边界的助手。打个比方斜杠命令像你给同一个实习生下达的标准任务单子代理则是你分别雇了前端专家、后端专家和测试专家你要谁干活就喊谁。前端细节问题直接问前端专家它不会用后端的思路来回答。我项目里就放了一个 frontend-reviewer 的子代理专门负责审查 Vue 组件的性能和状态管理它被触发时会用更苛刻的标准去检查代码输出比其他模板更专。不过坦白讲子代理的实际使用门槛比 CLAUDE.md 和斜杠命令要高你得花时间打磨它的系统提示词也需要在不同场景下反复测试边界。初期阶段我建议先把前两层用好等模板体系跑顺了再尝试引入子代理。2.4 三层怎么配合这三层结构不是各自孤立的而是一个递进的关系。CLAUDE.md 提供长期的项目记忆让 AI 在背景层就对齐斜杠命令在具体任务被触发时把任务目标、执行步骤和输出格式一次性传给 AI子代理则在需要更深专业度时接管以专门的视角执行任务。常规的小改动第一层就够了高频的标准任务用第二层需要深度专家能力的上第三层。我建议搭建模板库时也按这个顺序来先搭地基再逐步加高。3. 实战从零搭建一套 claude-code-templates 模板库3.1 设计目录结构既然项目标题叫 claude-code-templates我建议你直接把它当成一个独立的AI 协作配置仓库来管理。刚开始不需要追求庞大一个干净的可复用结构加上两三个高频模板就足够了。推荐目录结构长这样my-templates/ ├── CLAUDE.md └── .claude/ ├── commands/ │ ├── review.md │ ├── test.md │ └── commit.md └── agents/ └── frontend-reviewer.md注意 .claude 和 commands 目录都是首字母带点的隐藏目录别在编辑器里创建时写错。这个结构与 Claude Code 原生读取逻辑保持一致把整个目录丢进任何项目里都能立即生效。如果你不想污染项目仓库也可以放在用户级目录~/.claude/下作为全局模板两者的差异我会在后面的优先级小节里展开讲。3.2 编写 CLAUDE.md 的三个细节第一命令优先。把安装、构建、测试这些命令放在最前面、最显眼的位置。AI 判断力再强也不如直接把命令喂给它效率高。我见过不少人的 CLAUDE.md 写了大量架构说明但忘了写测试命令导致 AI 建议出一个根本不存在或跑不通的指令这在复杂 monorepo 里尤其容易发生。第二需要 AI 特别注意的点要独立成节。项目里总有那么几条容易踩坑的规矩比如时间字段要转本地时区删接口前先确认下游调用方。这些信息如果不写AI 每次都会犯同样的错写了但它藏在长文的角落里作用也不大。单独建一节AI 读取时会更容易把它当作高优先级约束。第三控制文件的长度。CLAUDE.md 会被完整加载进上下文窗口写太长会挤压模型处理当前任务的空间。我的经验是控制在合适篇幅以内只放 AI 必须知道的事实跟每次都要提醒不相关的内容宁愿不放。更详细的架构文档用链接把它引到外部站点而不是全文塞进文件里。3.3 写第一个斜杠命令代码审查模板直接给大家看我现在用的 review 模板完整内容你可以照着复制一份再按自己项目情况调整--- description: 对当前工作区的改动执行代码审查按严重程度输出问题清单 --- 请对当前工作区中的未提交改动执行代码审查。 ## 审查步骤 1. 先运行 typecheck 与 lint确认是否存在基础错误 2. 读取仓库根目录 CLAUDE.md按其中的项目约定执行后续检查 3. 根据 git diff 逐文件检查本次改动的逻辑 ## 审查维度 - 逻辑正确性是否存在明显边界遗漏、状态错乱或空值隐患 - 异常处理失败路径是否有兜底错误信息是否可定位 - 资源管理事件监听、定时器、连接池是否存在泄漏风险 - 命名质量变量/函数命名是否准确表达意图 - 性能隐患是否存在重复计算、无效渲染、N1 查询 ## 输出格式 按文件维度输出 Markdown 问题清单每一项包含 - 严重程度严重 | 中等 | 建议 - 位置文件路径及行号/函数名 - 问题描述 - 修复建议附可直接粘贴的示例代码 如果没有发现问题请直接输出未发现明显问题并简要列出你重点检查过的位置。这模板的精华在于**「审查步骤」和「输出格式」**。第一步强制它先跑 typecheck 与 lint可以筛掉很多基础问题输出格式则保证了无论 AI 怎么思考最后呈现给我们的永远是一份可归档的清单方便在 PR review 里直接引用。3.4 把模板库纳入 Git 与团队协作模板只有进入版本管理它的价值才能真正沉淀下来。我是把整个 claude-code-templates 仓库做成独立 Git 仓库来维护的然后在需要用到的业务项目里通过同构目录结构或者直接复制的方式引入。这样做有两个好处一是模板的更新有历史记录改坏了一个模板可以回滚二是它是可分享的资产团队成员之间不用靠聊天记录同步各自的模板。团队协作时我特别强调一点模板的变更也要走 code review。很多人觉得模板只是提示词而已改起来无所谓结果某次更新把审查维度擅自删掉两条后续所有 PR 的审查质量都受了影响。在我团队里凡是改动 .claude 目录下文件的 PRreviewer 都会额外确认一遍行为变化就像对待配置变更一样谨慎。4. 高频场景模板拆解同一种方法可以复制到任何任务4.1 测试用例模板让 AI 主动覆盖边界大多数人让 AI 生成测试习惯只描述 happy path帮我给这个函数写几个用例。结果 AI 生成的测试基本是复制粘贴的正常路径边界和异常路径全被忽略。这里的关键不是 AI 不会写边界测试而是你不说它就默认你想省事。测试模板的核心就是把边界和失败路径变成硬性要求。我常用的 test 模板结构是--- description: 为指定函数或模块生成完整的单元测试用例 --- 请为 {$ARGUMENTS} 生成单元测试。 ## 覆盖要求 1. 正常路径至少一个完整功能用例 2. 边界值空输入、极值、类型异常、数值上限/下限 3. 失败路径异常输入、依赖报错、超时场景 4. 时序场景如适用并发调用、顺序依赖 ## 命名规范 测试用例命名必须符合 should 行为描述 的格式。 ## 输出要求 - 先列出测试用例清单场景、输入、期望结果 - 再输出可直接运行的测试代码 - 使用项目现有测试框架与断言库 - mock 外部依赖时用注释说明 mock 原因注意到{$ARGUMENTS}这个变量了吗用户输入/test formatDateAI 就会把这个变量替换成 formatDate模板瞬间适配到任意目标。这是斜杠命令最实用的一个能力你在写模板时一定要用上。4.2 提交信息模板把规范变成默认行为提交信息是我见过团队里最难以统一的环节有人写 fix bug有人写 update codePR 历史一团糟。用模板把这个痛点解决掉非常容易而且几乎不需要调动 AI 的智力只需要约束格式。--- description: 根据当前 git 改动生成符合 Conventional Commits 规范的提交信息 --- 请根据当前工作区的 git diff 生成提交信息。 ## 格式要求 - type 从 feat / fix / refactor / test / docs / chore / style / perf 中选择 - scope 使用当前改动所属模块名如 auth、billing、upload - subject 控制在 50 字以内使用祈使句 - 如果 diff 包含破坏性变更必须在 body 写清 BREAKING CHANGE 与迁移方式 ## 输出内容 直接输出完整的提交信息不要附加任何解释。这里有一个我踩过坑之后的经验务必加上不要附加任何解释。不加这句的话AI 经常会在提交信息前后加一段这是我根据您的需求生成的提交信息你还要手动清掉。模板里明确要求输出纯净内容能省一次清理动作积累下来帮自己省了不少事。4.3 技术方案模板先分析约束再给方案让 AI 直接给技术方案它往往会跳进代码细节先甩出一大段代码再附带一句这是我建议的方案。实际上我更希望 AI 像资深工程师一样先弄清楚约束条件再给可选的方案对比。做法是在模板里明确编排它的思考顺序。我在 plan.md 里的编排方式是--- description: 针对给定需求生成技术方案先分析后给结论 --- 请针对下面的需求生成技术方案{$ARGUMENTS} ## 执行顺序 1. 先列出与需求相关的项目约束技术栈、既有架构、关键依赖 2. 梳理需求中的模糊点或未明确信息逐条列出来 3. 给出 2~3 个可选方案说明各自优缺点 4. 推荐其中一个并说明理由 5. 给出推荐的落地步骤按改动顺序列出 ## 输出格式 最终方案用 Markdown 输出约束分析、方案对比、推荐结论必须分开。重点在第 1 步和第 4 步。先逼它做上下文梳理能减少自作主张给出推荐理由是为了日后 review 时能追溯决策依据。这种方法拆解不只是 Claude Code 能用你把它扩展到任何 AI 对话场景都成立——只要你要求 AI先给分析、再给答案回答质量通常会有明显提升。5. 上下文管理与模板调优经验5.1 控制 CLAUDE.md 的体积前面提到过 CLAUDE.md 会被加载进上下文。很多人的第一个版本写得很爽什么都往里塞但用下来会发现一个严重副作用AI 确实记住了所有背景但执行当前任务时注意力明显涣散因为你塞的 60% 内容与当前任务无关。上下文窗口是有限资源每一条多余的长期记忆都在挤压模型处理当前问题时的推理空间。我后来定的标准是CLAUDE.md 只放不改就会导致错误的信息。技术栈、命令、硬性红线、目录约束够了。像团队每周三开评审会这种信息AI 不需要知道也大概率不会被用到放进去就是浪费 token。想了解更多文档用链接指向 docs 目录让 AI 在需要时自己去看而不是一次性全加载。5.2 用变量与命令分组扩展灵活性单单几个高频命令覆盖不了所有场景。灵活性的关键技巧有两个一是用好{$ARGUMENTS}传递参数二是用子目录对命令分组。Claude Code 支持在 commands 目录下再建子目录比如commands/code/review.md对应/code/review这样可以给命令加命名空间。我习惯把命令分成code/审查、重构test/单测、集成测试和doc/生成文档、生成变更日志三个分组。这样命令列表不会一团乱麻也方便不同角色关注自己常用的那组命令。5.3 调优模板的正确姿势从失败输出反推模板不是一次写完就完事它是需要迭代的。我常用的调优方法很朴素当你对 AI 的一次输出不满意别只改对话里的描述回去改模板把缺失的要求补进去。比如有次我让 AI 做代码审查它输出的问题清单里只写了问题描述没给修复建议。我当时的动作就是在模板里加了一条硬性规则每一项问题必须附带可粘贴的示例修复代码。下次再跑输出就标准了。持续一两个迭代周期后模板会趋向稳定。你会发现它越来越懂你——不是模型变聪明了而是你把期望值固化成了规则。这个过程跟带新人很像你每次交代任务时补充的那句话就是下一次培训手册里新增的条款。6. 常见问题排查与避坑实录6.1 模板不生效先检查这四个位置这个问题我问过自己也问过同事大多数时候是低级原因。第一个位置文件路径。CLAUDE.md 必须放在项目根目录而不是 src 目录或者子模块目录里。.claude/commands/也要放在项目根目录下不要嵌套进其他配置文件夹。第二个位置文件名大小写。斜杠命令的文件名就是命令名大小写要和你使用时的输入保持一致全小写最稳妥。第三个位置frontmatter 语法。description字段两侧的---不能省略格式错误会导致命令未被识别。第四个位置是否新建会话。修改 CLAUDE.md 之后正在进行的会话可能不会立即感知变化通常需要新开会话或者执行一次命令让它重新读取别改完文件就抱怨没生效。6.2 输出截断与指令冲突模板指令太杂或要求太多时AI 的输出容易被截断。一个典型情况是——模板里既要求完整分析又要求分步论证还要求输出超长代码最后 AI 写一半就停了或者开始自我重复。解决的思路是把一个大任务拆成多个子任务第一次指令先让它给分析和计划确认后再让它逐步执行。与其把所有要求压在一个模板里不如设计两个斜杠命令串起来用。另外项目 CLAUDE.md 和全局 CLAUDE.md 里的规则如果互相矛盾AI 会陷入混乱。全局写着优先使用 pytest项目写的是统一用 vitest它的行为就会反复横跳。排查时先检查这两层设置是否一致。6.3 团队协作中的模板冲突与版本混乱团队多人维护同一个模板库最常见的是改了一版影响所有人的问题。比如前端同事把 review 模板里的检查维度改成性能优先后端同事下一单代码审查就开始出现大量与性能无关的噪音。我的处理方式有两个一是团队模板的变更统一走 PR在描述里写明本次模板调整会影响哪类输出的格式二是不确定的时候模板里增加一个版本注释比如review-v2新增并发检查维度移除接口命名检查。这样诸位成员看到输出变化时能判断是模板更新了而不是 AI 抽风了。还有个小建议如果多项目共享同一套模板可以通过脚本或工具把模板仓库同步到各项目里避免各项目之间的配置越漂越远。这个同步动作也可以纳入 CI保证模板版本永远一致。自己在实际使用中体会最深的一件事是模板库的价值不在于一次性写得多完美而在于每一次对 AI 输出的不满意都能沉淀成一条规则让下一次更接近你要的结果。我处理过性能问题、UI 问题、代码规范问题到最后发现大部分问题其实都能靠写进模板、固定流程来解决。如果你现在每天还在为 Claude Code 的稳定性头疼先别急着怀疑模型能力试着从模板入手把你那些每次都要重复交代的内容固化下来效果可能会出乎你的意料。