做了几年 Claude Code 的深度用户，我越来越觉得：真正拉开体验差距的不是模型本身，而是你怎么把重复劳动固化成模板。刚接触claude-code自带的 templates 功能时，我也只是把它当成“存 prompt 的文件夹”，直到我自己整理出一套覆盖代码审查、提交信息生成、重构方案设计的模板库之后，才发现这东西本质上是在给 AI 助手做“肌肉记忆”。

这篇文章不聊官方文档里已经写烂的基础概念，重点讲清楚三件事：模板到底解决了什么真实痛点、每个配置项背后的设计逻辑、以及我从几个真实项目里踩坑踩出来的使用套路。如果你已经用了一段时间 Claude Code，但每次让它做代码审查、写提交信息时还在现场打一大段 prompt，这篇内容就是为你准备的。

1. 先搞懂 Claude Code 模板到底解决了什么痛点

1.1 从“每次重新说一遍”到“一次写好随便用”

用过 Claude Code 的人都有这种体验：让它帮忙审查代码改动，你至少要交代“看哪些文件、关注什么层面、输出什么格式”。这个过程看着不费劲，但一天重复七八次之后，你就是在反复消耗自己的注意力和上下文额度。

模板化最直接的价值，就是把“怎么说”从每次现场思考变成一次性投入。你把一段高质量、经过验证的指令存成.md文件，之后敲一个斜杠命令就能调用。写一次，用一年；个人用，团队也能用。它本质上是把你和 AI 之间最常发生的几类对话，固化成了一套稳定的接口。这样每次交互的起点不是空白，而是你精心设计过的最优状态，输出质量自然稳定得多。

我刚开始也觉得“多打几个字而已”，直到某天连续做了五次代码审查，每次都要重新写“请以安全视角优先、按严重程度分级、给出修改建议”，而且每次的措辞还不一样，输出质量也跟着波动。后来我把这段指令存成模板，稳定性和效率完全不是一个级别。

1.2 模板在 Claude Code 里的三种存在形态

Claude Code 里的模板不是一个笼统的概念，按存放位置和用途可以分成三类，我建议你先分清再动手：

• 自定义斜杠命令（Slash Commands）：放在~/.claude/commands/（全局）或.claude/commands/（项目级）目录下的 markdown 文件。文件名就是命令名，比如code-review.md对应/code-review。这是最常用的一类，也是这篇文章的重点。
• Agent 定义文件：放在.claude/agents/目录下，用于定义具有特定身份、能力和工具权限的专用 Agent。它比斜杠命令更“重”，适合需要长期扮演某种角色的场景，比如“后端架构师”“安全审计员”。
• CLAUDE.md 项目记忆：放在项目根目录或~/.claude/下的全局记忆文件。它不是按需调用的模板，而是每次对话都会自动加载的项目规则和背景信息。

一句话总结区别：CLAUDE.md 是“长期记忆”，slash command 是“按需技能”，agent 文件是“固定角色+专属技能”。三类配合使用，才能搭出一个完整的分层指令体系。很多人只盯着 CLAUDE.md 写项目说明，却忽略了 slash command 这个更高频、更灵活的入口，属实是捡了芝麻丢了西瓜。

2. 模板的工作原理与核心机制

2.1 斜杠命令是如何被加载和执行的

claude-code的 templates 不是某种神秘的黑盒机制，它的加载逻辑很简单直接。你输入/命令名的时候，Claude Code 会在两个位置按优先级查找对应的 markdown 文件：先查当前项目的.claude/commands/目录，再查用户全局的~/.claude/commands/目录。项目级模板会覆盖全局同名的模板，这跟大多数配置系统的“局部优先”原则一致。

文件内容的处理分两层：文件顶部的 YAML frontmatter 区域（用---包裹）负责声明元信息，比如命令描述、参数提示、可用的工具范围；frontmatter 下方的正文才是真正注入给模型的指令正文。这两部分一个管“怎么被调用”，一个管“怎么去执行”，分工非常清晰。

执行的时候，Claude Code 会把模板正文、你输入的命令参数、当前会话的上下文（包括对话历史和项目文件内容）合并成一个完整的 prompt，再交给模型处理。所以模板不是一个孤立文本，它只是 prompt 的“脚手架”，实际执行效果还取决于当前会话状态。理解了这一点，你设计模板时就要留出吸收上下文的入口，而不是写一堆脱离项目实际的空话指令。

2.2 frontmatter 里的关键配置项详解

frontmatter 是模板的大脑，但很多人写模板时要么完全不写，要么只写一个 description。我建议你至少掌握这几个字段，它们决定了命令的体验上限：

• description：显示在命令补全列表里的简短说明。建议写成“动词+对象+目标”的结构，比如“对当前分支的改动执行安全优先的代码审查并输出分级问题清单”。不能写“代码审查”，太模糊了。
• argument-hint：提示用户输入的参数格式。比如写[<文件路径>]，用户就知道可以跟一个路径参数。这个字段直接决定了模板能否被正确传参。
• allowed-tools：限定模型可以调用的工具白名单。比如审查代码时只给Read, Grep, Glob，不让它直接改文件。这是其他 prompt 工程里很难做到的事，是 CLI 原生工具的优势。
• model：指定该命令使用的模型规格。可以把耗时型任务（如全面重构）指定到更强的模型，把简单任务（如生成提交信息）指定到轻量模型，成本控制非常灵活。

注意：不同版本的 Claude Code 对 frontmatter 字段的支持有差异。model、allowed-tools这些字段在较新的版本中才稳定可用，升级后记得看一眼官方文档确认字段名。我遇到过同事用的旧版本不识别allowed-tools，模板直接报错的情况。

2.3 为什么模板能显著降低上下文浪费

这是我最想强调的一点。Claude Code 的上下文窗口有限，而每次对话里真正有用的信息密度，决定了模型输出的质量上限。不用模板时，你每轮都要重复指令描述，这些字面会挤占宝贵的上下文预算，等于让模型在“听你重复要求”和“读项目代码”之间抢空间。

用模板之后，指令描述只占一次性的空间，而且高度结构化、信息密度更高。模型把更多上下文窗口用在了阅读真实代码和分析问题上。实测下来，同样的代码审查任务，用模板之后输出的问题清单覆盖面更全，空话套话明显减少。这不是玄学，而是上下文分配机制的自然结果。

另外，模板还有一个隐性收益：减少 prompt 注入和指令漂移的风险。你每次手打指令，措辞总会有点出入，这些微小差异在模型眼里可能被放大成不同的执行倾向。模板把指令格式固定下来，输出行为的方差自然就变小了。

3. 手把手搭建一套自己的模板库

3.1 环境准备：确认版本与目录结构

动手之前，先确认你的 Claude Code 版本支持自定义模板。打开终端执行：

claude --version

如果版本过老，建议先升级：

npm update -g @anthropic-ai/claude-code # 或者如果你用其他方式安装，按对应的包管理器更新即可

然后创建目录结构。我的习惯是全局命令和项目命令分开管理：

# 全局模板目录（所有项目可用） mkdir -p ~/.claude/commands # 项目模板目录（建议纳入 git 管理） mkdir -p .claude/commands mkdir -p .claude/agents

为什么建议.claude/目录纳入 git 管理？因为模板本身是团队资产。你不想每次新人入职都重新口头传授一套审查规范，把模板提交到仓库里，新成员 clone 下来就能直接用，这是最低成本的团队标准化方案。

3.2 第一个模板：代码审查模板

我最推荐你创建的第一个模板是代码审查，因为它的使用频率高、收益立竿见影。在.claude/commands/下创建一个code-review.md文件，内容如下：

--- description: 对当前分支的代码改动执行安全优先的代码审查，输出分级问题清单 argument-hint: [<范围或文件路径>] allowed-tools: Read, Grep, Glob --- 你是一位资深的代码审查专家。请基于当前工作区的改动执行一次代码审查。 审查范围： - 默认审查所有未提交的改动（git diff）； - 如果用户提供了参数，则只审查 $ARGUMENTS 指定的文件或目录。 审查时必须关注以下层面： 1. 安全漏洞：注入、越权、敏感信息泄露、依赖风险； 2. 正确性风险：并发问题、边界条件、异常处理缺失； 3. 可维护性问题：命名混乱、重复代码、过度设计； 4. 性能隐患：明显的复杂度失控、不合理的资源使用。 输出格式要求： - 按严重程度分 P0 / P1 / P2 三级列出问题； - 每个问题必须包含：文件位置、简要说明、修复建议； - 最后单独列出改动中做得好的地方，控制在 3 条以内。 注意：本次只做审查，不要修改任何文件，也不要生成修复补丁。

这个模板我实际用了大半年，踩过的坑都在里面反应出来了。比如第一版没写“不要修改任何文件”，结果 Claude 偶尔会自作主张用 Edit 工具去改代码，审查变成代改，非常危险。所以我把allowed-tools限制为只读类工具，从机制上杜绝了这个问题。

3.3 再加一个：提交信息生成模板

代码审查模板管“改得对不对”，提交信息模板管“改的是什么”。在/commands下创建commit-msg.md：

--- description: 根据当前改动生成符合 Conventional Commits 规范的提交信息 argument-hint: [<提交说明>] --- 根据当前 git diff 生成一条提交信息，遵循 Conventional Commits 规范。 执行步骤： 1. 运行 git diff --staged 查看已暂存的改动； 2. 如果没有暂存内容，则运行 git diff 查看所有未提交改动； 3. 分析改动类型，确定 type 前缀（feat/fix/refactor/docs/test/chore 等）； 4. 写一个不超过 72 字符的标题行； 5. 如有必要，补充正文说明改动动机和影响范围。 用户额外说明（如果有）： $ARGUMENTS 输出要求： - 只输出最终的提交信息，不要解释过程； - 使用祈使句，时态用一般现在时； - 正文按“为什么改 / 怎么改 / 影响什么”三层展开。

这个模板虽然简单，但实际用起来特别顺手。团队里如果规范了 Conventional Commits，这个模板就能保证每个人提交的信息颗粒度和风格一致。我个人经验是它的价值不在于“写得华丽”，而在于“流程固定”：它先查暂存区、再查工作区、再决定 type，每一步都有逻辑依据。

3.4 进阶：带参数的模板与自定义 Agent

斜杠命令真正强大之处在于支持参数传递。在模板正文中，你可以用$ARGUMENTS引用用户输入的内容，这在前面的模板里已经用到了。还有一个更精细的用法是参数占位符，语法类似$ARGUMENTS的变体或${1:默认值}形式，可以让用户只填关键变量：

--- description: 对指定文件进行重构方案设计 argument-hint: <文件路径> [重构目标] --- 请对 ${1:src/utils/parser.ts} 设计一套重构方案。 重构目标：${2:降低函数复杂度，提升可读性} 输出内容： 1. 当前代码的主要问题（不超过 5 条） 2. 重构后的目录结构或函数拆分建议 3. 分步实施计划，每步可独立提交 4. 涉及的风险点与测试策略

实际运行效果是：触发/refactor后，模板会引导你依次补充文件路径和重构目标，就像填表单一样。这种带槽位的模板适合那些需要多轮信息才能启动的复杂任务。

如果你想更进一步，可以创建自定义 Agent。在.claude/agents/下新建一个security-auditor.md：

--- name: security-auditor description: 专业安全审计助手，专注识别代码中的安全漏洞与风险 tools: Read, Grep, Glob, Bash model: sonnet --- 你是一名资深应用安全工程师。你的职责是： 1. 用安全视角审查所有代码改动； 2. 重点关注认证授权、输入校验、敏感信息、第三方依赖风险； 3. 对发现的问题给出可复现的验证步骤和修复建议； 4. 始终用“风险等级+受影响代码+复现路径+修复建议”的结构输出。

之后在 Claude Code 会话中，你可以让模型切换到指定 Agent 来工作，或者用--agent security-auditor指定启动角色。这比普通模板多了“身份约束”和“固定工具集”两层能力，适合需要高度分工的团队协作场景。

4. 实战案例：用模板规范一个前后端项目的日常迭代

4.1 场景描述与模板组合方案

理论讲再多，不如看一个完整场景。这里分享一个我实际带过的项目：一个典型的前后端分离应用，前端 React + TypeScript，后端 Node.js + PostgreSQL，三个人协作开发，代码走 MR 流程。

当时我们遇到的典型问题是：每次 MR 之前的自查质量参差不齐，有人只测了主流程就提 MR，代码审查全靠 reviewer 人工看，效率低且容易漏。我们最终用模板搭建了这样一套组合方案：

这套组合的底层逻辑是：把强制动作变成低成本动作。如果你让开发者在提 MR 前“好好自查”，每个人对“好好”的理解是不一样的。但如果你让他执行一次/code-review，他只需要敲几个字，剩下的交给模板引导的流程。命令的确定性，带来了流程的确定性。

4.2 执行流程与实测效果

举一个具体的执行场景。某次我改完一个用户登录模块，涉及密码校验逻辑和 session 管理。按习惯先执行/code-review，因为改了鉴权相关代码，我额外加了参数指定了安全审查深度，模板自动定位到auth/目录下的改动文件。

模板输出的问题清单里有一个 P1 级别的问题：密码错误时没有统一的返回结构，导致前端的错误提示逻辑冗余。这个问题如果靠人工自查大概率就漏了，因为功能本身是正常的，只是接口契约上的隐患。修复之后我执行/commit-msg，模板自动生成了fix: unify auth error response structure这样的提交信息，标题行长度和措辞都符合团队规范。

从头到尾我只做了两件事：定义命令、执行命令。分析和输出完全由模板引导完成。实测一个迭代周期下来，MR 被 reviewer 打回的次数减少了大概一半，而且打回原因从“低级错误”变成了“业务理解不一致”这类更本质的问题。模板不是万能药，但它的确把人的注意力从重复检查中释放出来，去处理更高层级的事情。

4.3 模板内容的迭代与版本管理

模板不是写好就完事，它需要像代码一样持续迭代。我们团队的做法是：每次使用模板时，如果发现输出中存在共性的偏移（比如总是漏掉某种类型的 bug、审查风格太激进或太保守），就在 MR 里顺带提一个模板修改意见，定期统一完善。

有几个典型的迭代场景：

• 负面反馈注入：如果连续几次审查都没发现某种类型的问题，而后来某次线上故障恰恰是这类问题导致的，就在模板里增加一条对应的审查关注点。
• 去噪：如果模板固定输出的一些检查项在项目里完全不适用，果断删掉。冗余指令会占用上下文，还容易让模型“为了检查而检查”。
• 参数槽位调整：当某个模板总是需要用户补充同样的信息时，把它提升为 frontmatter 里的显式参数，减少输入成本。

我把模板文件放在 git 仓库里管理，每次修改都走 MR 流程。刚开始同事会觉得“改个模板还走流程太小题大做”，但出了两次模板被改坏、影响所有人的事故之后，大家就认可了版本管理的重要性。模板库是你的团队 AI 流程的基础设施，基建改了必须留痕。

5. 常见问题与排查技巧实录

5.1 命令不生效或找不到模板

这是新手最容易遇到的问题。我总结的排查顺序如下：

1. 确认文件扩展名是.md，文件名不能有空格或特殊字符；
2. 确认文件放在了正确的目录：项目级在.claude/commands/，全局在~/.claude/commands/；
3. 确认当前会话能识别新命令。有些版本需要重启会话才能加载新模板，或者输入/后按 Tab 刷新命令列表；
4. 检查模板文件名是否与内置命令冲突。比如你创建了一个help.md，很可能不生效，因为/help是保留命令。

提示：如果实在排查不出来，用/status或/context看看 Claude Code 实际加载的上下文里是否包含了你的模板目录。这个操作能快速确认是加载层的问题还是执行层的问题。

5.2 frontmatter 解析失败

frontmatter 看起来简单，但 YAML 解析对格式要求很严格。我遇到最多的两个坑：

• description 里写了冒号后面跟空格的内容，比如description: 检查: 全部代码，YAML 会把后半段当成嵌套结构解析导致报错。解决方法是整个值用单引号包起来。
• allowed-tools 写了不存在的工具名，模板执行时会因为工具调用失败而中断。工具名必须和 Claude Code 文档里列出的完全一致。

一个实用建议：写完模板后先在测试项目里跑一次看看是否报错，再放进团队共享目录。别拿正式项目试错。

5.3 模板输出不符合预期

有时候模板能正常触发，但输出质量完全不行。这时候要区分是“指令不清晰”还是“上下文不足”。

指令不清的典型表现是输出内容空泛、跟项目代码脱节。解决方案是检查正文里是否包含了“读取哪里、关注什么、输出什么格式”这三要素，缺哪个补哪个。

上下文不足的典型表现是模型一直说“我无法查看具体的代码”，或者输出明显基于猜测。这种时候要检查模板里是否遗漏了触发工具调用的指令。比如审查代码模板里就应该明确写“运行 git diff 查看改动”，而不是默认模型会自己去看。AI 不会主动做你没让它做的事，至少在命令行工具里，指令的显式程度和执行效果成正比。

5.4 团队协作中的模板同步问题

多人使用模板库时，最常见的两个麻烦是：

• 项目级模板没进 git：如果.claude/被.gitignore忽略了，新人 clone 下来就没有模板。建议在项目根目录显式加入.claude/。
• 全局模板各自为政：每个开发者自己改了全局模板，导致同一命令在不同人手里的行为完全不一样。业务相关的模板尽量走项目级并纳入 git，个人偏好（比如输出语言、措辞风格）才适合放全局。

我们最终的实践结论是“项目级为主、全局为辅”。代码审查、提交信息这类跟代码库强相关的模板全部放项目级，而在全局只保留与项目无关的通用工具类命令。

5.5 一个小技巧：模板与 CLAUDE.md 的分工

最后分享一个让两层指令体系不打架的技巧。CLAUDE.md 里只放“项目背景、代码结构、架构约束、测试命令”这类稳定且每轮对话都需要的事实型信息。凡是“按需执行、有明确输出格式”的任务指令，一律做成模板。

为什么会打架？因为如果你把审查规范、提交规范全部塞进 CLAUDE.md，每次对话都会加载这些长文本，占满上下文，同时这些规范在非相关任务里完全用不上。而如果把项目事实塞进模板，模板执行时模型缺少背景知识，输出的上下文关联性也会变弱。事实放记忆，任务放模板，这个分工原则让我少踩了无数个上下文浪费的坑。

在这个分工体系下，一次对话的加载成本是：CLAUDE.md 提供背景基线，触发模板时再注入任务指令，两者各司其职。这个思路也可以扩展到 agent 文件中，让不同角色负责不同任务域。

用过一段时间之后，你会慢慢感觉到：模板库就是你和 AI 协作的最优实践沉淀。每次你发现“这次指令写得特别好，输出结果很满意”，都值得把它固化成一个模板。这比收藏别人的 prompt 有效得多，因为它是从你自己项目的真实土壤里长出来的。