Claude Code 用了一段时间之后，我最大的感受是：工具本身再强，如果你每次都从零开始描述需求、重复交代背景、反复纠正它的风格，那体验就大打折扣。真正让 Claude Code “越用越顺手”的关键，不在模型，而在你给它的那套模板。今天想认真聊聊 claude-code-templates——也就是给 Claude Code 用的提示词模板、CLAUDE.md 配置、命令脚本和技能定义的组合方案。我会把整套东西从思路到实操拆开讲清楚。
这篇文章适合谁？如果你已经装好 Claude Code 但总觉得它“不够懂你”，或者你带团队、想让大家用 AI 写代码时风格统一、产出质量稳定，那这篇文章基本就是冲着你来的。我会从模板思维讲起，再落到实际文件怎么写、命令怎么配、坑怎么避，最后给你一份可以直接抄作业的模板仓库结构。
1. 整体设计与思路拆解
1.1 模板到底解决的是什么问题
先说一个很实际的痛点。Claude Code 每次会话都是独立的，它不记得你昨天让它遵守的代码风格，不记得你项目里哪几个目录是自动生成的、不该乱动，也不记得你写提交信息时习惯用 Conventional Commits。每次开新会话，你都得把这些背景重新解释一遍。解释得清楚，它干得漂亮；解释得模糊，它就给你自由发挥，然后你花更多时间改。
模板（templates）就是干这个的。它把“你希望 AI 如何工作”的全部约束、流程、角色设定、常用操作，沉淀成项目里的文件。Claude Code 启动时会自动读取这些文件，把里面的规则注入到上下文中。你不再重复交代背景，AI 也一上来就带着正确的“人设”和“工作习惯”干活。
我见过很多人的误区是：模板就是写一段“你是资深前端工程师，请写出高质量的代码”这种话。说实话，这种东西加进去跟没加差不多。真正有用的模板，解决的是三个具体问题：
- 上下文浪费：把规则写成文件后，AI 不用靠你每句话里的碎片信息去猜，它的注意力能集中在真正的任务上。
- 风格漂移：同一个项目里，今天写的代码和上周写的代码风格不一致，模板就是给 AI 的“风格锚点”。
- 流程缺失：AI 直接甩给你结果，不做需求澄清、不列影响面、不写测试，模板可以强制它按流程走。
这套思路不限于 Claude Code，任何对话式编程工具都适用。但 Claude Code 的模板体系做得最深，值得单独拿来说。
1.2 模板的四个层级：从全局到专项
设计模板前，先理解它存在的几个层级。逐层递进，各管各的范围：
第一层：全局规则（CLAUDE.md 放在用户主目录）。管所有项目。比如你的通用编码偏好、禁止事项、常用工作流。我习惯把“不要修改自动生成的文件”“提交信息用英文，遵循 Conventional Commits”“先阅读相关代码再动手”这类放这里。
第二层：项目规则（CLAUDE.md 放在项目根目录）。管当前项目。项目技术栈、目录结构、构建命令、代码风格、特殊约定。这一层最重要，几乎是每个项目必须有的。
第三层：命令模板（.claude/commands/ 目录）。把高频操作封装成斜杠命令，比如/review、/commit、/test。本质上是用模板定义一段固定的指令流程，一个命令就是一个可复用的 AI 工作流。这块我后面细讲。
第四层：技能模板（.claude/skills/ 目录）。定义 AI 可以按需调用的专项能力，每个技能包含说明、规则、示例。比如“数据库迁移专家”“React 性能分析工具”。它比命令更重，适合复杂、多步骤、需要知识库支撑的任务。
这四个层级叠加起来，就是你给 Claude Code 的一个完整“职业人格系统”。设计的时候要遵守一条原则：全局管通用，项目管具体，命令管流程，技能管能力。别把项目专属的规则塞到全局文件里，也别把一条简单命令写成重技能——层级乱了，维护成本会暴涨。
2. 核心细节解析与实操要点
2.1 CLAUDE.md 的加载机制：规则如何进入上下文
CLAUDE.md 这个名字，本质上是给 Claude Code 用的“项目公约”。它不像常规配置文件那样被解析成结构化数据，而是像一份文档一样，在会话开始时被整体读入上下文。启动时 Claude Code 会自动加载用户主目录下的全局文件，然后加载当前项目根目录下的文件。它会自动处理路径问题，你不用在笔记本目录里打开终端就担心找不到文件。
除了自动加载，CLAUDE.md 还支持通过@路径语法手动引用其他文档。比如项目根目录的 CLAUDE.md 里放核心规则，把详细的设计规范拆到 docs/ 下的分文件，需要时由 AI 主动读取。这里有个细节值得注意：Claude Code 会在引用时显示文件摘要，帮助 AI 判断是否展开全文。所以被引用文件的“第一屏内容”很重要——开头就要说清楚这个文档管什么、什么时候该读它。
另一个重要机制是 glob 限制。你可以在 CLAUDE.md 里指定哪些路径生效。默认情况下，会有若干通用文件自动被包含，比如 package.json、tsconfig.json、README.md。但我建议你手动在文件里做一个“生效范围”声明，明确告诉 AI：这个文件适用于 src/ 下的所有代码，不适用于 generated/ 目录。尤其全员共用一套 CLAUDE.md 的团队，必须靠 glob 控制规则边界。
注意：CLAUDE.md 的规则是“软约束”。Claude Code 会优先遵守它读到的规则，但当用户指令足够明确时，用户指令优先级更高。别指望规则能拦得住用户主动要求做的操作。
2.2 角色设定与响应结构：让 AI 进入工作状态
模板里最有“人味”的部分是角色设定。我见过写得好的角色设定，不是“你是专家”这种空话，而是把 AI 的思维方式、决策偏好、表达风格一次说清。一段比较有效的写法是：
# 角色 你是一名拥有 10 年经验的深度全栈工程师，擅长在大型代码库中做影响面分析。 你写代码前先看上下文，你重视可读性胜过技巧，你默认写测试。 你的代码评审意见必须基于具体代码位置，不允许说空话套话。这个写法的核心是：用行为描述替代身份描述。你说“经验丰富”，它不知道怎么表现；你说“写代码前先看上下文”“默认写测试”，它就能照着执行。
响应结构也值得在设计模板时固化。Claude Code 的默认回复没有固定形状，你可以要求它按你定义的框架输出。比如：
# 输出要求 在开始编码前，必须依次完成： 1. 梳理需求背景和约束，列出你的理解并指出不明确之处； 2. 输出实现方案，说明技术选型和理由； 3. 列出受影响的文件清单； 4. 获得确认后再写代码。 写代码时必须包含：实现说明、测试方案、可能的坑。有很多人会问：这样会不会拖慢速度？实际上，代码一旦改错，返工代价远超这几步。模板让 AI 先想清楚再做，长期看是省时间的。
2.3 命令与技能：把高频操作变成“斜杠快捷键”
斜杠命令是 Claude Code 模板体系里最容易被忽视的一个功能。它的本质是：你定义一个命令名，然后把一段指令文本绑上去。执行时 AI 会按照文本内容完成整个工作流。我把常用命令写成了这么几个：
- /review：AI 以资深 reviewer 身份审查当前分支的代码变更，对比主分支，按严重程度列出问题，输出修改建议。
- /commit：AI 执行 git diff 分析变更类型，按 Conventional Commits 规范生成提交信息，要求信息结构为 type(scope): subject + body。
- /test：AI 分析最近改动的模块，找到对应测试文件，跑测试并修复失败用例。
- /doc：为指定函数或模块生成内部文档，包含设计意图、使用示例、边界条件。
每个命令就是.claude/commands/目录下一个带 frontmatter 的 Markdown 文件。frontmatter 里可以定义参数占位符（比如$ARGUMENTS），AI 在调用时会把斜杠后面的文本填充进去。
技能（skills）比命令更重。技能通常包含一组文件：SKILL.md 说明触发条件和执行流程，references/ 目录放参考文档，同时可以用脚本辅助执行。适合的场景是：跨多个文件、需要领域知识、流程较长的任务。你可以把团队最佳实践沉淀成技能，AI 遇到对应场景就自动调用，而不是每次靠人肉描述。
3. 实操过程与核心环节实现
3.1 从零搭建一套项目模板：完整文件示例
理论讲完，直接上实操。假设你接手一个 TypeScript + React 项目，想搭一套适合团队使用的 Claude Code 模板。我的做法是先在项目根目录建一个CLAUDE.md，内容分区写在同一个文件里：
# 项目技术栈 - 前端：React 18 + TypeScript 5 + Vite - 状态管理：Zustand，禁止使用 Redux - 样式：Tailwind CSS 4，禁止引入 CSS 框架 - 测试：Vitest + Testing Library - 包管理：pnpm，禁止使用 npm install # 工作约束 1. 使用 pnpm 安装依赖；不要修改根目录下自动生成的文件； 2. 所有新组件必须写类型定义，禁止滥用 any；Props 需要注释说明用途； 3. 函数式组件优先，不使用 class 组件； 4. 代码提交信息使用 Conventional Commits 格式，英文书写。 # 响应要求 - 当你看到需求，先输出方案和影响文件，再动手编码； - 修改后必须运行类型检查（pnpm type-check）和相关测试； - 如果方案涉及第三方库，需说明选型理由并建议替代方案。这段文件不长，但每一条都有实际价值。技术栈部分明确告知 AI 工具链；工作约束部分避免了最常见的破坏性行为；响应要求部分让 AI 按可接受的节奏工作。这套模板投入成本只有 10 分钟，收益是以后每次会话 AI 都能按预期方式干活。
3.2 一步步配置斜杠命令与技能
接下来配置命令。/commit命令经常被我用，以它为例，文件内容大致是这样：
--- description: 生成符合规范的提交信息 --- 你是一名资深开发工程师。请执行以下步骤： 1. 运行 `git diff HEAD` 和 `git status`，理解当前变更； 2. 分析变更类型，归类为 feat、fix、refactor、docs、test、chore 等； 3. 提取具体的变更内容和影响范围； 4. 生成提交信息，格式严格为 `type(scope): subject`，subject 用祈使句； 5. 如果有破坏性变更，在提交信息尾部添加 `BREAKING CHANGE:` 说明； 6. 只输出提交信息，不要附加任何解释。有个细节值得反复强调：AI 在生成提交信息时容易漏看暂存区内容。所以我在命令里强制它先跑git diff HEAD和git status两个命令，确认全部变更后再总结。这就是模板的价值——不是给 AI 一套说辞，而是规定它的工作流。
再早点学会用引用（imports）。你看官方文档时可能会注意到，许多优秀模板会在文件顶部通过@path引用其他配置文件。比如有人会在 CLAUDE.md 里写“参照 @.claude/rules/backend.md 的规则进行后端开发”。这可以让规则模块化，而不是所有规则堆在一个大文件里。我的一个后端项目就这样切分：CLAUDE.md 只做总览和工作流说明，详细约束全部放在 .claude/rules/ 下的独立文件里，AI 按需引用。
3.3 模板仓库组织：一套模板管多个项目
如果你玩过多个项目，会发现模板其实可以沉淀成一套可复用的东西。我个人会在一个独立目录里维护“模板源”，结构如下：
claude-code-templates/ ├── global/ │ └── CLAUDE.md # 通用规则，软链到用户主目录 ├── project/ │ ├── CLAUDE.md # 项目级模板，拷贝到各项目根目录 │ ├── commands/ # 斜杠命令集合 │ │ ├── commit.md │ │ ├── review.md │ │ └── test.md │ ├── skills/ # 技能集合 │ │ └── react-perf/ │ │ ├── SKILL.md │ │ └── references/ │ └── rules/ # 按领域拆分的规则文件 │ ├── backend.md │ ├── frontend.md │ └── git-workflow.md └── scripts/ └── sync.sh # 一键同步模板到项目sync.sh可以做成一个简单的复制脚本，把项目模板复制到新项目里。团队用的话，模板源放在 Git 仓库里，新成员 clone 下来跑一次 sync 脚本，环境就一致了。这种“配置文件即代码”的管理方式，比口头约定“开发时注意代码规范”靠谱一个量级。
4. 常见问题与排查技巧实录
4.1 规则不生效：命中范围与优先级
我遇到过很多次：CLAUDE.md 写了一大堆，但 AI 就是无视。排查时先从三个角度入手：
- 文件位置对不对：全局文件必须放在用户主目录，项目文件必须放在项目根目录。放错位置 AI 根本读不到。
- 路径匹配对不对：如果规则只对某个子目录生效，检查 glob 写法。比如你有
packages/admin和packages/core两套代码，规则里写匹配 packages/admin/**，AI 在改 core 代码时自然会忽略该规则。 - 指令内容优先级：用户的具体指令会覆盖规则。所以如果 AI 没遵守规则，先确认用户是否曾明确要求过相反操作。
还有一点容易被忽略：AI 会优先遵守声明了“最高优先级”的规则。你在文件里把某条规则标注为“此规则优先级高于所有其他规则（除非用户明确覆盖）”，它的执行强度会明显提升。
4.2 上下文被撑爆：模板越长，AI 越“看不见”
模板不是写得越多越好。Claude Code 的上下文窗口是有限资源，模板内容会占用这部分空间。当模板过长时，AI 反而会“选择性失明”，只记住开头和结尾的规则，中间的全被忽略。
我的经验是：一个 CLAUDE.md 文件控制在 80 行以内，超过这个量就拆文件。拆出来的规则文件靠@引用按需加载。你不能指望 AI 一开始就把所有规则都吃透，而是要让它知道“有这么个文件存在，需要时去读”。把规则从“常驻内存”改成“按需加载”，上下文压力会小很多。
比如一个项目里既有前端又有后端，最适合的做法不是写一个 200 行的大文件，而是拆成CLAUDE.md + rules/frontend.md + rules/backend.md。AI 做前端任务时只引用前端规则，做后端任务时再引用后端规则。
4.3 命令不执行或效果不符：逐行排查
斜杠命令不生效，八成是文件格式问题。命令文件必须放在.claude/commands/目录下，文件名不能带空格，frontmatter 里的description是必填项。还要注意，参数占位符$ARGUMENTS只能在命令的正文里使用，写在 frontmatter 里不会生效。
如果命令执行了但效果不对，多半是指令文本写得不具体。比如命令里写“分析代码并提出优化建议”，AI 就会泛泛而谈。要写“列出 Top 3 性能瓶颈，注明文件、行号和优化理由”。另外，命令文件里包含需要进一步解释的引用时，AI 通常会优先读取这些引用的内容，引用路径写错会让命令执行结果跑偏。
4.4 模板版本迭代：规则也要跟着项目演进
最后聊一个容易拖垮团队模板体系的坑：模板不更新。项目技术栈升级了、目录结构调整了、人事变动导致职责边界改了——这些变化如果在模板里没有同步，AI 就会按旧规则工作，产出落后于项目现状。
我建议把模板纳入 code review。每次改动 CLAUDE.md 或命令，都走一遍常规 PR 流程。另外，模板里只写与 AI 协作相关的约束，不要把团队管理制度写进去。过度约束反而会让 AI 束手束脚。
我习惯每隔一段时间执行一次“模板体检”：拉一个真实需求跑一遍 AI 工作流，观察它在哪一步表现不佳、在哪一步频繁返工，把痛点转化成新的规则。模板的价值是持续演进的，它不是写一次就完事的东西。
整套 claude-code-templates 思路，说到底就是“把你想让 AI 怎么干活的全部意图，以文件形式固化下来”。一旦跑通，你会明显感觉到 Claude Code 从一个“每次都要重新磨合的临时工”变成一个“熟门熟路的固定协作者”。我个人建议第一次搭建时别求全，挑最痛的两个点先解决，比如提交信息规范和代码风格约束，跑几天后再逐步补充其他规则。模板是越长越难维护，从“够用”出发往往走得更远。
