如果你最近装了 Claude Code，大概率会遇到这么个场景：同一个需求，每次都要把背景、约束、代码位置重新敲一遍；换了个项目，AI 写出来的代码风格跟你的工程完全不是一路人；好不容易调试出一个好用的提示词，过几天想用却怎么也想不起来当时是怎么写的。
模板就是用来治这些毛病的。
claude-code-templates说白了不是某个单一文件，而是一整套让 Claude Code 按你的规矩办事的“套路总集”。它可以是一个仓库、一个目录、甚至一张随手存下来的思维清单，核心目标只有一个：把那些每天都在重复的上下文、指令、规范，固化成可以一键调用的模板，让每个项目、每个成员都能站在同一条基线上去使用 AI 编程助手。
这篇文章我把自己在多个项目里反复调整后的模板体系完整拆开讲，包含目录结构、文件写法、参数化设计，以及一堆文档里查不到的排查心得，适合已经把 Claude Code 跑起来、但觉得“差点意思”的人参考。
1. 模板到底解决了什么问题
1.1 不是提示词，而是工作流
很多人一听到“模板”，第一反应是“不就是把提示词存起来吗”。这个理解只对了一半。
提示词解决的是“某一次对话里 AI 怎么回应”，但模板解决的是“AI 在整个项目周期里如何持续稳定地工作”。这是两个完全不同的层面。举个例子：你写一条“用 React 写一个表单组件”的提示词，效果取决于这句话背后有没有注入项目技术栈、代码风格、组件目录、测试要求这些上下文。而模板做的，就是把这些上下文永久挂在项目里，让你每次只需要发号施令，不需要把背景故事重新讲一遍。
我做过的项目里，最明显的一次对比是：没上模板之前，让 AI 在旧项目里改个接口，它会把整个项目当成默认的 REST API 风格去处理，哪怕我们用的是 tRPC；上了模板之后，AI 第一眼就知道“这个项目用 tRPC，改接口要顺带改 types 和 router”，完全不需要你多解释。
1.2 模板体系的三层递进
用了一段时间后，我把模板的价值分成了三个层次，越往上越管用：
第一层：惯例层。把项目的代码风格、目录结构、技术选型、命名规范写清楚。这一层负责让 AI 的输出“像这个项目的人写的”。比如是否用分号、组件文件怎么命名、状态管理用 zustand 还是 redux，这些如果不写，AI 默认给你一套社区平均风格，放进项目里怎么看怎么别扭。
第二层：流程层。把高频任务的动作序列固化下来。比如“新增一个列表页”这种活儿，标准流程是：先写类型定义，再写 API 调用，再写组件，最后补空状态和加载状态。没有模板时 AI 可能会跳过类型、直接一把梭，有了模板它就会按部就班。
第三层：策略层。这是最容易忽略但价值最高的一层。它规定的是“AI 在什么情况下应该停下来问人、什么情况下应该自作主张”。比如“当存在多个实现方案时先列出对比再选择”或“当需求存在歧义时先总结你的理解让我确认”，这类规则能把 AI 从盲目的执行者变成一个带判断力的协作者。
这三层分别对应模板里的不同文件，需要在规划时想清楚自己到底要解决哪一层的问题。
2. 模板体系的五个核心积木
在这一节我会把一套可落地的 Claude Code 模板体系拆成五个积木，每个积木承担不同职责。理解这五个东西的定位，比直接抄别人的模板更重要。
2.1 CLAUDE.md：项目的大脑
只要是正经用 Claude Code 做项目的人，都绕不开CLAUDE.md这个文件。它是项目根目录下的一个 Markdown 文件，Claude Code 每次启动对话时会自动加载它，把里面的内容作为整个会话的“默认记忆”。
我的经验是，CLAUDE.md应该回答三个问题：
- 这个项目是干嘛的？一句话说清楚产品定位、核心业务逻辑。
- 这个项目怎么组织的？代码目录结构、关键技术栈、构建/测试命令。
- 这个项目有什么潜规则？命名风格、错误处理偏好、禁止事项、各类约定。
需要注意，CLAUDE.md不是越长越好。模型每次对话都要读它，写得跟长篇小说似的，不仅占上下文窗口，还会稀释真正重要的信息。我见过有人把整个 wiki 塞进去，结果 AI 反而把关键约定给忘了。好用的CLAUDE.md通常控制在 200 行以内，用最直白的话把最核心的规则讲清楚。
2.2 自定义 Slash 命令
Claude Code 支持在.claude/commands/目录下放 Markdown 文件来定义自定义命令。每个文件名就是一个/命令名，比如.claude/commands/refactor.md对应/refactor。
这是模板体系里最直观、也最容易出成果的部分。你可以给高频任务做一套命令模板，之后只需要输入/commit就能让 AI 按你规定的格式生成 commit message，输入/review就能让 AI 按你的代码审查清单逐项检查代码。
命令文件里面可以写指令，也可以引用变量。Claude Code 支持用$ARGUMENTS来获取用户在命令后面输入的参数，这让命令变得非常灵活。比如定义一个/test命令，后面跟上具体的模块名，就能生成针对性的测试建议。
2.3 Hooks：自动化钩子
如果说命令是“手动档”，那 Hooks 就是“自动档”。Claude Code 的 Hooks 机制可以监听各种事件，比如文件编辑后、对话开始时、命令执行前后，在特定时机自动注入内容或触发动作。
我日常用得最多的是两种：一种是在会话开始时自动读取某个状态文件，让 AI 知道当前进行到哪一步了；另一种是在每次编辑代码文件时自动追加一条“文件风格确认”的隐式约束，防止改着改着就放飞自我。
Hooks 的配置在.claude/settings.json里声明，事件类型在官方文档里能查到，我这里不赘述。关键思路是：Hooks 适合放“必须无条件生效”的规则，而不是放“有时需要有时不需要”的柔性指引。后者更适合用命令或 CLAUDE.md 来处理，否则会变成过度约束。
2.4 Agents 子代理
Agents 是相对进阶的能力。简单理解，就是在主对话里可以“呼叫”一个专职代理来处理特定任务。每个 Agent 可以有自己的系统指令、自己的上下文文件，适合做垂直任务的深度处理。
模板体系里，我会为一些高难度的任务单独创建 Agent 模板。比如代码审查 Agent、架构设计 Agent、SQL 优化 Agent。在主任务里遇到需要深度思考的环节，就呼叫对应 Agent 去处理，而不是让主对话的上下文被一堆专业细节塞满。
这样做的好处有两个：一是隔离上下文，避免主对话被无关信息污染；二是每个 Agent 有自己专注的规则，回答质量比“大而全”的主模型要高得多。
2.5 目录规范与命名
模板文件多了以后，目录规范就变得重要了。我目前的标准结构大概是：
project-root/ ├── CLAUDE.md └── .claude/ ├── commands/ │ ├── commit.md │ ├── review.md │ └── test.md ├── agents/ │ ├── code-reviewer.md │ └── sql-optimizer.md ├── hooks/ │ └── session-start.sh └── settings.json这套结构的核心原则就是按职责划分：命令是主动发起的，Agent 是深度委派的，Hooks 是自动生效的，CLAUDE.md 是全局常驻的。目录结构清晰了，团队成员上手成本才会低。
3. 从零搭建一套可复用的模板
知道了积木是什么，下面进入实战环节。我会带你从零走一遍完整的搭建流程，每一步都说明为什么这么做。
3.1 先梳理自己的重复劳动
很多人一上来就急着写模板文件，结果写完发现完全不好用，因为根本不知道自己要解决什么问题。我的建议是：先花半小时做一次“重复劳动盘点”。
拿一支笔，列出你使用 Claude Code 时最常做的五件事。对每件事，再列出你每次都要额外告诉 AI 的信息。比如：
- 写 commit message：每次都要提醒 AI 看 git diff、用 conventional 格式、不要加无关内容
- 代码走查：每次都要提醒 AI 关注安全性、性能、错误处理、边界条件
- 写单元测试：每次都要告诉 AI 项目用 vitest、测试文件放哪个目录、命名规则是什么
这些“每次都要额外吩咐”的东西，就是模板的第一批素材。把它们写进对应文件，以后就不用说了。
3.2 CLAUDE.md 的写法与踩坑
我建议直接从一个最小版本开始，后续逐步往里加。最小版本只需要四个段落：
# 项目概览 一句话说明项目是什么、给谁用。 # 技术栈 列出主要语言、框架、包管理器、测试工具、代码风格工具。 # 常用命令 - 开发：npm run dev - 测试：npm run test - 构建：npm run build # 代码约定 - 组件文件使用 PascalCase - 工具函数使用 camelCase - 状态管理统一使用 zustand - 错误信息必须写明可操作的解决方案写好之后测试一下，让 AI 做一个最简单的单文件改动，看看它的行为是否符合预期。如果它默认不遵守某些约定，就可以在CLAUDE.md里用更明确的语气再写一遍。
踩坑经验：不要写自相矛盾的规则。我踩过一次，CLAUDE.md 里写了“代码要精简”，同时又在另一段写了“每个函数都要写 JSDoc 注释”，结果 AI 写出来的代码非常精神分裂。模板合并之后相互冲突，模型只会随机遵守其中一条，甚至都不遵守。
3.3 命令模板的参数化设计
Slash 命令的价值在于“可复用”，而可复用的核心是参数化。Claude Code 的命令文件里可以借助$ARGUMENTS或提示词让用户输入补充信息。
以我最常用的/commit命令为例，文件大致是：
根据 git diff 生成规范的 commit message。 要求： 1. 使用 Conventional Commits 格式（feat/fix/refactor/docs/test/chore） 2. 第一行不超过 72 个字符 3. 如果涉及 breaking changes，必须加 BREAKING CHANGE 后缀 4. 不要添加任何 Co-Authored-By 等无用附加信息 当前 git diff: `$ARGUMENTS`这里的$ARGUMENTS会替换成用户跟在/commit后面的文字，也可以让它展开成 git diff 的引用。这个模板把“生成 commit message”这件事从头到尾约束住了，之后每次提交都能拿到格式一致的输出。
参数化的核心心得：不要试图把所有信息都写在命令里，只把“每次都会变”的部分提取为参数，把“永远不变”的部分写成规则。否则命令会臃肿得没人用。
3.4 一个完整的综合示例
下面我给一个稍微复杂一点的例子：定义一整套“从需求到实现”的工作流模板。这个模板不是为了某一次具体开发，而是为了把“拿到需求 → 设计方案 → 实现 → 自测”这个完整链路的动作固定下来。
我会在.claude/commands/implement.md里写：
你是本项目的资深工程师。请按照以下步骤处理需求： 第一步，复述需求。用三句话讲清楚你对需求的理解和关键约束。 第二步，识别涉及的文件。列出需要新增或修改的文件路径，并说明每个文件的作用。 第三步，设计实现方案。如果有多种方案，先用列表对比再选一个推荐方案，说明理由。 第四步，生成实现代码。严格遵守 CLAUDE.md 中的代码约定，每个文件写完后简要解释关键函数。 第五步，自测方案。给出至少两个测试用例或手动测试步骤，覆盖正常路径和异常路径。 需求内容： `$ARGUMENTS`这个命令的精髓在于把“思考过程”拆成了可见的步骤。每次调用它，AI 都必须先复述需求再动手，很大程度避免了“理解偏了还硬写”的情况。团队里用这套模板的新人，上手速度会比纯自由对话快不止一倍。
4. 常见问题与排查技巧实录
模板搭好只是开始，真正考验人的是日常使用中遇到的各种状况。这里整理几个我有代表性、也最影响体验的问题。
4.1 模板不生效：先确认加载路径
最容易犯的低级错误是把文件放错位置。记住一个核心原则：CLAUDE.md必须放在项目根目录，也就是你启动 Claude Code 时所在的目录；命令文件必须放在.claude/commands/下，后缀必须是.md；Agent 文件则在.claude/agents/下。
如果确认路径没错还是不生效，优先检查文件名大小写和扩展名。在 Linux/macOS 上，CLAUDE.md和claude.md是两个完全不同的文件。我自己就因为这个吃过一次亏，AI 完全不认小写版本，找了好久才发现是文件名打错了。
另外提醒一点：修改CLAUDE.md或命令文件后，当前会话里是不一定实时生效的。如果感觉改了没反应，可以重新开启一个会话再测试，大概率就好了。
4.2 上下文太长：模板叠加的代价
模板体系越来越完善后，容易出现的副作用是上下文不断膨胀。CLAUDE.md 要读、命令要读、Agent 要读、Hooks 又注入了额外内容，一来二去，可用上下文直接少了一大截。
我自己的处理策略是“分级压缩”：把全局通用的约定放在 CLAUDE.md 里，把偶尔用的长文档拆到单独文件里，只有需要时才引用。比如项目里有一套详细的数据库设计规范，那就不要整篇放进 CLAUDE.md，而是单独建一个docs/database-rules.md，在需要做数据库相关的任务时，让命令模板去加载它。
这个思路就像整理书桌：经常用的笔放在桌上，偶尔用的文件塞进抽屉，而不是把所有东西全摊开。
4.3 多项目共享模板：用 git 管理你的模板仓库
我维护了很多项目，如果每个项目的模板都是复制粘贴改出来的，那维护成本会很高。我选择的做法是建一个独立的模板仓库，用 git 管理，每个项目里只保留几个引用入口。
模板仓库的结构可以按“前端项目模板 / 后端项目模板 / 通用模板”分类。新项目启动时，把对应分类下的文件复制过去再微调信息。当模板本身更新时，手动同步到存量项目里。这个流程不算全自动，但胜在简单可靠。
如果想更自动化，可以把模板做成一个 CLI 脚本，运行new-project my-app --template react-ts就自动生成整套文件。这类工作值得做一次，后续节省的时间非常多。
4.4 团队协作：模板统一但允许个人覆盖
多人协作时，最怕的是每个成员都有自己的“私房模板”，导致 AI 行为在每个人机器上不一样。我的建议是：团队模板由一个人负责维护，放进仓库的.claude目录里随项目走，其他人不再另起炉灶。
同时，允许个人在~/.claude/目录下放自己的全局模板，专门处理那些「跟具体项目无关的个人偏好」。这样既保证了项目的统一性，又保留了个人灵活度。
注意：团队模板里不要写死某个人的名字、偏好或工作习惯。模板应该服务所有人，而不是变成某个成员的“个人定制版”。团队模板的立场应当中性、通用、可执行。
5. 我踩过的坑和心得
最后分享几条经过不少折腾才想明白的经验，希望能帮你少走弯路。
5.1 模板不是越多越好
很多人在入坑模板后会有一种冲动，恨不得把所有事情都做成模板。我给项目加过十几个自定义命令，最后发现常用的永远是那么三四个，其余的全在吃灰。
模板的收益是“高频任务的标准化”，代价是“维护成本的增加”。如果一个动作你一个月都用不到一次，那它就不值得做模板，临时输入几句指令反而更灵活。保存模板前先问自己：这件事接下来一个月我至少会做几次？答案不明确，就别做。
5.2 提示词要讲人话，别写“论文体”
我在早期写模板时犯过一个错误：每个规则都写得特别正式、特别严格，结果 AI 的输出变得非常“机械感”。后来才明白，模板里的指令不需要像法律条文那样滴水不漏，反而应该像你平时跟同事交代工作那样口语化。
比如“注意代码质量”这种话就没有任何约束力；但“这段代码别用 any 类型，实在要用也必须在旁边加个注释说明为什么”就很具体，模型一听就懂。模板写得越像真实的人类对话，模型的理解就越准确。
5.3 从最小可用开始迭代
最后一点，也是我认为最值得强调的：不要试图一次到位。最好的模板不是设计出来的，而是用出来的。一开始只需要一个能跑的 CLAUDE.md，加一个/commit命令，其他的一边用一边补。
我见过有人花了两天时间精心设计一整套模板体系，结果第一天用下来发现命令之间逻辑冲突，又重写了一遍。我从多次重写里得到的经验是：先让最小可用版本跑起来，真实需求会告诉你下一步往哪个方向迭代，这比闭门造车高效得多。
关于模板的分享就到这里。最后的最后，如果你还在犹豫要不要用模板，我的体会是：花一小时把 CLAUDE.md 写好，再用半小时定义一两个最常用的命令，接下来的每一轮开发都会比之前顺畅一截。这套投资，回本速度远比你想象中快。
