我先说明一个背景：如果你已经试用过 Claude Code，应该会有一种感觉——它单次对话很聪明，但放进一个真实项目里，如果不加约束，它会在你用过时的 API、风格混乱的代码、毫无章法的提交信息之间反复横跳。越用越觉得，问题不是模型不够强，而是你没给它一份"怎么帮你干活"的操作手册。这份操作手册，就是 Claude Code 的模板体系，也就是社区里常说的 claude-code-templates。
这篇文章不谈概念，直接拆我实际在用的一套模板方案，包括 CLAUDE.md 怎么组织、自定义斜杠命令怎么写、团队怎么共享，以及我踩过的坑。不管你是刚接触 Claude Code 的新手，还是已经把它接入工作流的老手，照着这份思路搭建，可以让 Claude Code 从"偶尔惊艳"变成"稳定靠谱"。
1. 为什么 Claude Code 需要模板体系
1.1 从裸奔到规范化：CLAUDE.md 的作用
Claude Code 本身是一个跑在终端里的 AI 编程代理，它通过对话来理解你的意图，然后直接操作文件、跑命令、写代码。问题在于，每次对话的上下文都是有限的，而且模型对你的项目一无所知——它不知道你的代码风格、不知道你的测试要求、不知道哪些路径不能动、不知道你希望它先做计划还是直接开工。
所以 Anthropic 设计了 CLAUDE.md 这样的记忆文件。它的作用类似给项目写一份"员工入职手册"：在每次对话启动时，Claude Code 会把这些内容读入上下文，让它知道该以什么身份、什么规则、什么流程来工作。没有这套东西，Claude Code 就像一个新来的工程师，能力强但不知道该听谁的指挥。
我用了几周裸奔之后最明显的感受是，它对同一个问题的回答风格飘忽不定。今天生成的函数用了 TypeScript 的 enum，明天就给你写 union type；今天会主动补测试，明天又完全忘记。这不是模型变笨了，而是缺少稳定指令。模板的第一个价值，就是把"符合你团队习惯的行为"固化成文字，让每次会话都在同一套规则下运行。
1.2 模板库解决了什么痛点
很多人会手动写一段话告诉 Claude Code 该怎么做，比如"请审查我的代码""帮我写测试""检查类型错误"。这种临时指令的问题在于，它不够稳定、不够完整、而且每次都要重复输入。时间长了你会发现，真正该沉淀的不是某一句指令，而是一整套可复用的模板库。
claude-code-templates 这个项目标题下，收藏的正是这类东西。它通常包含两类文件，一类是全局的 CLAUDE.md，放在~/.claude/CLAUDE.md，作用于所有项目；另一类是项目级的 CLAUDE.md，放在仓库根目录，只对该仓库生效。再加上自定义斜杠命令（slash commands），放在.claude/commands/目录下，把那些高频操作——代码评审、测试生成、提交信息整理——变成一键触发的固定流程。
模板库解决的痛点很明确：第一，不用每次消耗宝贵的上下文来重新解释规则；第二，把团队约定通过文件形式沉淀下来，新人接入零成本；第三，把复杂的多步工作流固化成命令，降低出错的概率。后面我会逐一展开这三类文件怎么写才有效。
2. 模板体系的核心构成拆解
2.1 CLAUDE.md 全局配置模板：角色、风格、操作红线
全局 CLAUDE.md 是所有项目的默认底色。我建议至少包含四块内容：角色定义、语言与输出风格、默认工作方式、操作红线。
角色定义决定了 Claude Code 以什么视角看待自己。比如我会写"你是一名具有十年经验的资深前端工程师，擅长 TypeScript、React 和 Node.js"，并补充"你说话直接，不客套，不重复用户说过的话"。这行字看起来简单，实际影响很大——它决定了后面所有回答的语调和深度。
语言与输出风格这块，我会明确指定"回答使用中文""代码注释用英文""提交信息用英文"等。这里有一个容易被忽略的点：如果不指定语言，Claude Code 往往会根据代码里的变量名和注释风格切换语言，导致注释中英混杂，极其难受。写清楚之后，这个问题基本消失。
默认工作方式我通常会写几条行为约定，比如"面对复杂任务先制定计划，拆解步骤后再动手""修改代码前先读相关文件，确保改动一致""遇到不确定的需求时，列出你的假设并提问，而不是擅自决定"。这些约定能在关键时刻拦住它的自作主张。
操作红线是全局模板里最有价值的部分，也是我强烈建议每个人根据自己习惯定制的部分。我自己的红线包括：不要删除任何文件除非明确要求；不要运行你无法完全理解的 shell 命令；不要在没有测试的情况下重构核心逻辑；打包或构建命令执行前先确认依赖状态。这些规则不可能被模型完美遵守，但有总比没有强，能显著降低它在关键路径上闯祸的概率。
2.2 项目级 CLAUDE.md：按仓库定制的关键
项目级 CLAUDE.md 比全局模板更细，它描述的是这个仓库特有的东西。我通常在项目级的 CLAUDE.md 里写这些内容：
- 项目简介与技术栈：用三五行说明这个仓库是干什么的、用了什么框架和语言。
- 目录结构说明：标注哪些目录是核心源码、哪些是自动生成的、哪些不该动。
- 常用命令清单：开发服务器启动命令、测试命令、构建命令、代码检查命令，直接给出一组
npm run dev之类的明确指令。 - 代码规范与约定：组件文件命名、状态管理方式、样式方案、目录职责边界。
- 已知限制与注意事项：比如某些文件是后端生成的不可手改，某些 API 已经废弃，某些测试需要 mock 特定数据。
这么写的原因很实际。Claude Code 在一开始对项目是一无所知的，它不读 package.json 也不会主动看目录。你如果不把"测试命令是什么""哪些文件不能动"写清楚，它大概率会在猜的过程中浪费步骤，甚至猜错。写好了，它首次对话就能以接近团队老手的效率工作。
举个例子，我之前维护的一个 monorepo 项目里，Claude Code 经常把注意力放到 website 目录下，而核心代码都在 packages/core 里。我在项目 CLAUDE.md 里加了一段"核心业务逻辑位于 packages/core/src，修改前必须阅读该目录下的相关文件；website 是文档站点，仅允许修改内容页面"后，它的行为立刻被约束住了，不再在无关目录浪费时间。
2.3 自定义斜杠命令：把高频操作固化成命令
Claude Code 支持自定义斜杠命令，这可能是模板体系里最被低估的功能。默认的/review、/test等系统命令很好用，但真正舒服的是你自己写的命令。
自定义命令的存放位置是.claude/commands/，每个命令对应一个 Markdown 文件，文件名就是命令名。比如你创建一个.claude/commands/feat.md，那么在对话里输入/feat就会触发这个文件的内容，让 Claude Code 按你写好的步骤执行。
文件里面除了给模型看的指令正文，还有一个可选的description字段放在 YAML frontmatter 里，用于在命令列表里显示简介。这个设计很像给模型写了一个小巧的"脚本"，把零散的对话指令包装成了稳定的流程。
我强烈建议从自己最高频的三个操作开始写：提交信息整理、代码评审、测试生成。这三个场景的输入输出相对明确，模板收益最高。等用顺手了再扩展其他命令，比如"导出 API 类型""更新文档""修复 lint 错误"。
3. 可复用的模板示例：直接抄作业
3.1 代码评审模板
代码评审是我用得最多、效果也最稳定的一个模板。它的核心不是让 Claude 简单看一遍代码说"看起来不错"，而是给它一个结构化的分析框架。
我的.claude/commands/review.md内容大致是：
你是一名资深工程师，正在做一次严格的代码评审。 请检查当前分支相对主分支的改动，重点从以下几个维度分析： 1. 逻辑正确性：有没有边界情况没处理、错误处理缺失、状态更新遗漏。 2. 类型安全：有没有使用 any，有没有类型断言掩盖真实问题。 3. 性能隐患：有没有不必要的重复计算、循环里执行异步操作、组件渲染链路过长等。 4. 可维护性：函数是否过长，命名是否清晰，是否遵循项目既定模式。 5. 安全性：有没有 SQL 注入、XSS、敏感信息输出等问题。 输出格式： - 先给出总体结论：通过 / 需修改 / 需讨论。 - 按严重程度列出问题：严重、中等、轻微，每个问题给出文件位置、具体行号、问题说明、修改建议。 - 不要客套，不要夸代码，专注于问题和风险。 - 使用中文输出。这个模板的要点有三个。第一，明确"检查当前分支相对主分支的改动"，否则 Claude Code 会把整个项目都读一遍，既慢又失焦。第二，输出格式固定，方便我快速扫一眼就看到重点。第三，明确"不要客套"，否则它会花半页篇幅夸代码风格好，浪费上下文。
我实际用下来的感受是，这个模板能稳定地发现三类问题：未捕获的异常、类型边界没处理、以及新代码和项目旧模式不一致。它不一定能替代人的判断，但作为提交前的最后一道检查，效率提升非常明显。
3.2 测试用例生成模板
让 Claude Code 写测试，它通常都能写，但写得对不对是另一回事。我早期的失败经验是，它对测试框架的使用方式想当然，经常生成一堆跑不过的测试。原因在于它不知道项目用的是 Vitest 还是 Jest，不知道你的 mock 风格，也不知道现有测试放在哪个目录。
所以我的.claude/commands/tests.md模板，第一步是让它读取现有的测试文件和配置文件，再开始写。模板里这样写：
你的任务是为指定的函数或组件编写测试用例。 前置步骤： 1. 先阅读 package.json，确认测试框架与脚本命令。 2. 阅读测试目录或相邻 `__tests__` 文件中已有的 2-3 个测试，模仿其风格与 mock 方式。 3. 再阅读目标函数或组件的源码，梳理其输入输出与依赖关系。 编写要求： - 覆盖正常路径、边界值、错误路径三类用例。 - 使用项目现有测试框架，不引入新依赖。 - mock 外部依赖时使用与现有测试一致的风格。 - 断言要具体，避免只检查"不报错"。 - 给出运行单个测试文件的命令，方便我验证。这个模板的效果立竿见影——从那以后，Claude Code 写的测试基本都能一次跑通。它背后的逻辑说起来也简单：模型在模仿现有测试风格这件事上做得比凭空生成好得多。你只需要在模板里把"先模仿再生成"拆成明确的步骤，它就会执行。
3.3 提交信息规范模板
提交信息看起来是个小事，但团队协作里它反而最容易产生摩擦。一个统一格式的提交信息，能让 review 历史、生成 changelog 都顺畅得多。Claude Code 自带/commit命令，但它生成的提交信息不一定符合团队规范。我的自定义模板解决了这个不一致。
我的.claude/commands/commit.md内容是：
根据当前的代码改动生成规范的 Git 提交信息。 要求： - 使用 Conventional Commits 规范，格式为 type(scope): subject。 - type 优先级：feat / fix / refactor / perf / docs / test / chore / style。 - subject 用英文祈使语句，不超过 50 个字符，不以句号结尾。 - 如果改动较复杂，在正文用要点说明改动原因和影响范围。 - 先输出 git status 和 git diff --stat 的简要内容，确认改动符合描述。 - 不要直接执行 git commit，只输出提交信息。这个模板最后一句"不要直接执行 git commit"是我特意加的。原因很实在，Claude Code 有时候会在你不注意的时候帮你把提交执行了，而它生成的信息不一定是你想要的。让它只输出信息、由你来粘贴，既保留了效率又保留了控制权。
3.4 重构与迁移模板
重构是一个风险极高的操作，Claude Code 有很强的重构能力，但也正因为能力强，更容易在重构中顺手改坏东西。我给它的定位是"谨慎的重构执行者"，模板里写的是循序渐进的步骤：
执行代码重构任务，但必须严格遵守以下流程： 1. 先输出改动方案，包括涉及的文件列表、每次改动的目标、风险点，等确认后再继续。 2. 对每个文件重构前，先阅读原文件完整内容，理解其功能。 3. 重构后立即运行类型检查和测试命令，确认没有破坏现有功能。 4. 遵守项目现有代码风格，不顺手重构无关代码。 5. 如果重构过程发现依赖其他模块，先停下来描述依赖关系，而不是强行修改。 6. 最终输出改动文件清单与测试结果摘要。我特别吃这个模板里"先输出方案等确认"这一步。它把主动权交回我手里，让重构过程从"一下全干完"变成"可监督的渐进过程"。这样即使模型执行错了，损失也被限制在单次步骤里，回滚成本很低。
4. 构建自己的 claude-code-templates 实操过程
4.1 目录结构与初始化
搭建自己的模板库不需要任何额外工具，需要的只是几个目录和 Markdown 文件。我建议按下面的结构组织：
~/.claude/ # 全局用户目录 ├── CLAUDE.md # 全局规则，作用于所有项目 └── commands/ # 全局斜杠命令（可选） ├── review.md ├── tests.md └── commit.md your-project/ ├── CLAUDE.md # 项目规则，只在本仓库生效 └── .claude/ └── commands/ # 项目级斜杠命令 └── review.md全局目录~/.claude/CLAUDE.md写了之后，所有新会话都会自动加载。项目级CLAUDE.md放在仓库根目录，被 Claude Code 自动识别。全局命令和项目命令的差异在于，全局命令在任何项目里都能用，项目命令只在该仓库里能触发，适合存放这个项目特有的工作流。
还有一个细节：命令目录如果不存在，手动创建即可。Claude Code 在启动时会自动扫描这些目录，不需要额外注册。我自己习惯把模板库也同步到一个 Git 仓库里，这样换新电脑或者同事要参考时，直接 clone 就行。
4.2 模板的调试与验证
写模板跟写代码一样，需要调试。我发现的最快验证方式，是直接用一句话触发命令，然后观察它的行为是否符合预期。比如写完 review 模板后，随便切到一个有改动的分支，输入/review，看它第一轮输出是不是按照你指定的格式来的。
如果发现它没有遵守模板里的某个要求，我通常会先检查是不是措辞太模糊。模型对"尽量""大概"这类词的理解很发散，模板里如果写"检查潜在问题"，它就会自由发挥。更高效的做法是写"从逻辑正确性、类型安全、性能隐患、可维护性、安全性五个维度分析"，把抽象要求变成具体维度。
还有一个常见问题是命令文件里的指令优先级不够。我会把最关键的约束放在文件开头，并用"必须""不要""先做 X 再做 Y"这类强指令。比如 review 模板里如果没有"不要客套"这句，它一定会客套，这是我反复实践得到的教训。
4.3 版本管理与团队共享
模板库值得纳入版本管理，尤其是在团队里使用时。Claude Code 的工作质量高度依赖模板质量，而模板会随着项目演进不断优化。把它放进 Git 仓库，记录下来每次改动的理由，后续回溯就很方便。
团队共享这件事，我强烈建议把项目级模板直接提交到代码仓库里，而不是靠口头传播。原因很简单，模板只有跟着代码走，才能保证每个人用的都是同一套规则。新人 clone 仓库后，Claude Code 自动读到项目模板，不需要任何额外配置，体验一致性会好很多。
全局模板可以在团队内拉一个私有仓库共享，里面放通用规则和通用命令。任何成员更新后，其他人通过 pull 同步。这样既保持了灵活性，又避免了每个成员各自维护一套、内容越漂越远的问题。
5. 常见问题与排查技巧
5.1 模板不生效 / 规则被忽略
用模板的时候，最让人头大的问题是"我明明写在 CLAUDE.md 里了，它怎么还是不听"。这个问题我遇到的次数不少，原因一般有两个。
第一个原因是优先级冲突。Claude Code 同时加载全局 CLAUDE.md 和项目 CLAUDE.md 时，如果规则互相矛盾，模型会自行选择它认为更合理的一条。比如全局模板说"回答使用中文"，项目模板说"代码注释用英文"，它可能把"回答使用中文"理解成所有文字都要中文，导致代码注释也变中文。解决办法是明确区分领域，加一句"代码注释使用英文，对话回复使用中文"，而不是让模板猜。
第二个原因是模型上下文被截断或遗忘。Claude Code 的上下文窗口虽然不小，但在长会话里早期读入的规则会被挤掉。这时候你直接说"请先阅读项目根目录的 CLAUDE.md，并严格执行其中的规则"，通常就能拉回来。不建议依赖模型自己记住所有规则，关键节点的提醒是必要的。
5.2 提示词冲突与优先级
多份模板叠加时，冲突几乎不可避免。我的解决思路来自我在工程里常用的分层策略：全局模板只放底层通用规则，项目模板放该项目的具体约定，命令模板放特定任务的执行步骤。每一层只写本层该管的事，不要越级。
举例来说，全局模板里不写任何与具体技术栈相关的内容，项目模板里不写与单次操作相关的细节。这样三份模板职责清晰，冲突概率大幅下降。如果仍然出现冲突， Claude Code 通常会以后读入的内容为准——项目模板晚于全局模板读取，命令文件在触发时才读入，所以命令文件的指令权重最高。你可以利用这个特性，让最关键的约束出现在命令文件里。
5.3 上下文膨胀与记忆污染
模板文件写得越长，每次对话消耗的上下文就越多。这也是一个容易被忽略的坑——我一开始追求把规则写全，结果 CLAUDE.md 写了上千行，每次对话光读规则就要占掉不少窗口，留给实际代码分析的上下文反而少了，回答质量明显下降。
我的建议是 CLAUDE.md 控制在 30 到 50 行为宜，只写那些真正影响行为的关键规则。细节性的内容放到命令文件里按需读取，而不是一股脑塞进常驻上下文。如果一个规则你从没观察到 Claude Code 违反过，那就别写；如果写了一条规则但从不影响实际行为，那就删掉。这样模板库越用越精炼，而不是越堆越沉。
5.4 调试信息排查
最后给一个实用技巧：当你不确定 Claude Code 到底读到了哪些内容时，可以在对话里直接问它，比如"你当前读到的 CLAUDE.md 内容是什么""项目级模板里关于测试的规则是什么"。它会原样输出它读到的内容，你可以借此确认模板是否真的生效、是否存在加载错误。
还有一个排查方法是做一个最小化实验。如果你怀疑某条规则没起作用，就把模板里的内容删到只剩那一句，开一个新会话触发测试，看它是否遵守。如果遵守，说明是上下文冲突；如果不遵守，说明这句措辞有问题。这个方法虽然简单粗暴，但往往能最快定位问题。
我在实际使用中还有一个体会：模板不要一次写完，它更像项目和团队规则的沉淀。今天写三条，用了两周发现哪条不管用就删掉，哪条很重要但没写就补上。Claude Code 的价值在于对话智能，而模板的价值在于把这种智能稳定地导向你想要的方向。随着你对自己的工作流越来越了解，这份模板库会变得比任何一段单次对话都更有价值。
