如果你团队里已经有人在用 Claude Code 写代码，大概率会遇到这样的场景：同一个项目，三个人三条对话风格。A 让 Claude 生成的函数带完整的类型注解和 JSDoc，B 忘了加，C 干脆让 Claude 自由发挥，连文件命名都五花八门。代码评审的时候，一半时间花在争论"这个接口为什么没有注释"上，而不是逻辑本身。这不是 Claude 不够聪明，而是你根本没有告诉它团队的标准是什么——这就是 claude-code-templates 要解决的核心问题。
Claude Code 的模板体系，说白了就是把团队里"好的沟通方式"沉淀成一份可以被 AI 自动读取、自动遵守的约定文件。它能干三件事：一是给 Claude 注入项目的长期记忆，比如技术栈、目录结构、编码规范；二是把高频任务封装成带参数的斜杠命令，比如一键生成单元测试、一键做代码评审；三是通过配置让 AI 在特定时机自动执行某些动作。适合谁用？任何在用 Claude Code 写业务代码的开发者、想统一团队 AI 协作规范的技术负责人、以及被"每次都重写一遍 prompt"搞烦的个人开发者。下面我从原理到实操，把整套模板玩法拆开讲清楚。
1. Claude Code 模板到底是什么：从一次憋屈的对话说起
先讲个我自己的真实案例。之前接了一个维护老项目的活儿，项目用的是十年前的技术栈，目录里全是历史遗留代码。我让 Claude Code 帮我改一个接口，它自信满满地生成了一堆现代写法，还顺手把文件位置搞错了。我当时的反应是："这 AI 怎么这么不靠谱？"后来冷静下来才发现，问题在我——我没告诉它这是什么项目、有哪些约定、文件放在哪。Claude Code 只能看到你给它的上下文，你指望它"自己悟"，它就给你一个"想当然"的结果。
1.1 没有模板之前，AI 协作的三个老大难
第一个问题是失忆。每次新开一个会话，Claude 对你的项目一无所知。它不知道你们用 Vue 2 还是 Vue 3，不知道单测框架是 Jest 还是 Vitest，不知道代码里禁止使用any。你每次都把同样的话重复一遍，它每次都能给出不一样的理解。
第二个问题是不一致。哪怕你每次都在 prompt 里写了"请遵循 Airbnb 风格"，Claude 也有可能在你长篇大论里丢失重点。你写了 800 字的规范，它真正遵守的可能只有前三条。这不是模型能力不行，是人类书写 prompt 的方式就不适合承载长期规范。
第三个问题是重复劳动。很多任务是高度相似的：写接口、写测试、做 review、打 commit 信息。每次都重新组织语言，效率极低，而且不同人组织出来的 prompt 质量差异巨大。有人能把需求讲清楚，有人讲完 Claude 完全做错方向。
1.2 模板的本质：把团队规范变成默认值
claude-code-templates 这套玩法的本质，是把"经验"变成"默认值"。就像你去一家餐厅，菜单上不会写"请用干净的盘子"，但后厨默认会这么做。模板文件就是那份后厨操作手册，它是 Claude Code 启动时的强制上下文，不需要你每次提醒。
更关键的是，模板解决了prompt 质量参差的问题。你想让 AI 输出符合团队风格的代码，与其靠每个人自觉写 prompt，不如把规范写进模板里，让 AI 在生成代码之前就先读到这些约束。这样哪怕新来的同事完全没经验，只要有模板在，AI 的配合度就有底线保障。
1.3 模板系统的分层架构：从个人到家再到项目
Claude Code 的模板不是只有一种，它有一套清晰的分层体系，越具体的层优先级越高：
| 层级 | 位置 | 作用范围 | 典型内容 |
|---|---|---|---|
| 用户级 | ~/.claude/CLAUDE.md | 当前用户所有项目 | 个人偏好、常用工具链、输出语言偏好 |
| 项目级 | ./CLAUDE.md或.claude/CLAUDE.md | 当前项目所有会话 | 技术栈、目录结构、编码规范、常见任务流程 |
| 子目录级 | ./子目录/CLAUDE.md | 限定子目录内任务 | 该目录专属的代码规则，比如前端目录只写 React 规范 |
| 命令模板 | ~/.claude/commands/与.claude/commands/ | 按需触发 | 可带参数的斜杠命令，如/test、/review |
这个设计非常像 CSS 的层叠样式表：全局默认规则铺底，项目级规则覆盖用户级，子目录级规则进一步细化。Claude 在处理某个路径下的文件时，会把这些层的规则按优先级组合起来，组成它的初始上下文。理解这个分层，你就知道往哪一层放什么内容了。
2. 模板类型全景拆解：哪些模板值得沉淀
我见过不少人把模板简单理解成"一个 CLAUDE.md 文件"，其实只用到了一半。真正让模板体系发挥价值的，是把它拆成几个不同类型的资产，分工配合。下面按我自己的使用频率和收益排序，逐一拆解。
2.1 CLAUDE.md / AGENTS.md：项目级长期记忆
这类文件的核心使命是建立项目的"世界观"。Claude 每次对话开始时都会读取它，所以它应包含那些"每个开发者入职第一天就应该知道的事"。我一般会在里面写四块内容：
第一块是项目定位与技术栈。用一两句话讲清楚项目是干什么的，然后列出核心依赖和框架版本。这里有个容易被忽略的点：一定要写版本。Vue 2 和 Vue 3 的写法差异巨大，你不写版本，Claude 就可能按最新版的语法去改旧代码。
第二块是目录结构说明。不需要把每个文件夹都列出来，只说明几个关键目录的职责，以及"新增文件应该放哪"的判断逻辑。比如后端项目的 service、repository、controller 分层，Claude 拿到这个信息后才能生成符合架构的代码。
第三块是编码规范与禁忌。这是最重要的部分。我会明确写"禁止全局使用 any"、"组件命名必须用 PascalCase"、"所有接口返回结构必须包含 code/message/data 三个字段"这类硬性约束。注意，写禁忌比写建议更有效，因为 AI 对负面约束的执行率明显更高。
第四块是常见任务的工作流程。比如"新增一个接口需要修改哪几个文件"、"跑测试的命令是什么"、"部署流程是哪种"。这些事情看似琐碎，但每次让 Claude 少走弯路，节省的就是真金白银的上下文窗口。
至于 AGENTS.md，你可以把它理解成 CLAUDE.md 的"通用化版本"。它被越来越多的 AI 编码工具（包括 Codex、Cursor 等）读取，是社区正在形成的开放标准。如果你的团队以后可能换工具，直接用 AGENTS.md 可以避免将来把所有规范重写一遍。Claude Code 本身也认 AGENTS.md，我现在的项目会直接写 AGENTS.md，省事。
2.2 斜杠命令模板：可参数化的流程助手
如果说 CLAUDE.md 是"被动读取"的规范，那斜杠命令就是"主动触发"的技能。它们的存放位置是 commands 目录，一个 Markdown 文件就是一个命令。调用方式是在 Claude Code 的对话框里输入/命令名 参数。
这种模板最大的价值是把多步骤任务封装成一个入口。比如我的项目里有个/review命令，它会先让 Claude 读取指定文件的 git diff，然后按照代码审查的标准逐条检查安全、性能、可维护性，最后输出一份带严重级别分级的问题清单。如果没有这个命令，我每次都要手写一段很长的 prompt，中间还可能漏掉某个检查维度。有了命令模板，输入一行文字就够了。
斜杠命令支持参数占位符，这是它灵活性的关键。你可以在命令文件里用$1、$2代表第几个参数，用$ARGUMENTS代表全部原始参数。命令模板还能通过 Frontmatter 设置元信息，比如description会被显示在命令列表里，argument-hint会提示用户该传什么参数，model可以指定这个命令使用哪个模型。
2.3 Hooks 与自动触发模板：话说一半不如话不留
Hooks 是模板体系里的"自动化机关"。通过配置文件里的 hooks，你可以让 Claude Code 在特定事件发生时执行外部操作。比如：
PreToolUse：在 Claude 调用某个工具前触发，可以用来限制它只能访问白名单内的文件。PostToolUse：在工具执行完后触发，比如每次文件写入后，自动跑一遍 linter。Stop：在 Claude 每次回复结束后触发，可以把对话摘要写到日志里，方便复盘。Notification：长时间任务完成后发通知。
注意：Hooks 的使用要克制。我见过有人配置了复杂的 hook 链，结果 Claude 每次读写文件都要触发一堆脚本，速度慢得离谱，而且 hook 报错还会打断正常流程。Hooks 适合做"轻量校验"，不适合做"重量级流水线"。我的建议是，先只配置一两个高频且低成本的 hook，跑稳定了再加。
3. 实操：从零搭建一套可用的模板库
理论讲完，直接上实操。我带大家完整过一遍，从规划目录到写完模板，再到接入团队工作流。这套方案我实际用在多个项目中，照着做基本能直接落地。
3.1 第一步：规划目录结构与命名规范
先看最终的目录结构，有个整体印象：
项目根目录/ ├── AGENTS.md ├── .claude/ │ ├── commands/ │ │ ├── review.md │ │ ├── test.md │ │ ├── commit.md │ │ └── api.md │ └── settings.json ├── src/ │ ├── backend/ │ │ └── CLAUDE.md # 后端子目录专属规范 │ └── frontend/ │ └── CLAUDE.md # 前端子目录专属规范 └── docs/ └── coding-standards.md # 详细规范文档几个设计决策解释一下。首先，根目录用AGENTS.md而不是CLAUDE.md，原因是通用性更强。其次，commands 目录只放四五个高频命令，不要一上来就整一堆，维护成本会让模板形同虚设。最后，把详细规范单独放在 docs 下，AGENTS.md 里用相对路径链接过去，避免模板文件过长。
命名规范上，斜杠命令文件用小写英文，语义要明确：review、test、commit、api。不建议用中文文件名，因为终端里切换输入法敲路径很别扭。命令内部如果还有子分类，可以直接加二级目录，比如commands/frontend/gen-component.md，调用时会自动变成两级命令。
3.2 第二步：编写项目级 AGENTS.md
这是整套模板的心脏。给你看一个经过裁剪的真实示例：
# 项目全局约定 ## 项目简介 这是一个面向中小电商的订单管理系统，前端 Vue 3 + TypeScript + Vite， 后端 Node.js 18 + Express + Prisma，数据库为 MySQL。 核心业务域：商品、订单、库存、支付。 ## 目录结构 - src/frontend：前端应用，页面放在 views/，公共组件放在 components/ - src/backend/routes：接口路由层，只做参数校验和请求分发 - src/backend/services：业务逻辑层，核心逻辑都在这一层 - src/backend/models：Prisma 数据模型与查询封装 ## 编码规范（必须遵守） 1. 后端接口返回结构统一为 { code: number, message: string, data: any } 2. 禁止在 routes 里编写业务逻辑，一律走 services 3. 前端组件统一使用组合式 API（setup 语法糖） 4. 禁止使用 any，无法确定的类型用 unknown 并做收窄 5. 所有新增函数必须有 JSDoc 或中英文注释，说明入参出参 ## 常见任务流程 - 新增后端接口：routes 添加路由 → services 添加实现 → models 编写数据查询 → 手动测试 - 新增前端页面：views 下创建组件 → 配置路由 → 对接 API 类型定义 - 运行测试：pnpm test - 代码检查：pnpm lint这个文件有几个值得注意的地方。第一，它的信息密度很高，没有废话，因为每一行都在占用 Claude 的上下文窗口。第二，规范条目用明确的动词开头，比如"禁止""必须""统一为"，不给 AI 留模糊地带。第三，给出"常见任务流程"时尽量短，让 Claude 知道做某类事应该按什么顺序操作，而不是自己瞎猜。
写完根目录的 AGENTS.md 之后，如果项目里不同子系统差异很大，可以在子目录里再写局部 CLAUDE.md。比如src/frontend/CLAUDE.md里只写前端特有的规范，它会和根目录 AGENTS.md 一起被加载。注意，子目录文件和根目录文件的加载顺序是：Claude 在处理该路径下的文件时，会同时参考两者，离文件更近的规范优先级更高。所以子目录规范只需写"增量规则"，不要重复根目录内容。
3.3 第三步：编写斜杠命令模板
命令模板是团队效率提升最明显的部分。以代码评审命令为例，看一个完整的实现：
--- description: 对 Git 改动进行代码评审，输出分级问题清单 argument-hint: <commit范围或文件路径列表> allowed-tools: Bash, Read --- 你是一名资深代码评审专家。请对 $1 范围内的代码改动进行评审。 评审维度： 1. 安全性：是否有注入风险、敏感信息泄露、权限校验缺失 2. 正确性：是否存在并发问题、数据一致性隐患、边界条件遗漏 3. 性能：是否有明显的重复计算、循环内查库、大对象无谓拷贝 4. 可维护性：命名是否清晰、函数是否职责单一、是否有过度设计 输出格式： - 每个问题单独列出，标注严重级别：[P0] 必须修复 / [P1] 建议修复 / [P2] 可选优化 - 给出具体文件路径和行号 - 每个问题附一句修改建议 - 如果某个维度没有问题，明确地说"未发现问题"，不要强行凑数 注意： - 只评审 $1 范围内的内容，不要越界阅读其他文件 - 如果 $1 为空，默认读取当前分支相对于主分支的 diff - 评审意见使用中文这段命令的精髓在于：开头就限定工具范围（只允许 Bash 和 Read），防止 Claude 借评审之名改动代码；强制输出格式，让结果稳定可读；要求标注严重级别，方便抽查人快速抓重点。而且我在 Frontmatter 里写了argument-hint，用户在输入/review后会自动看到参数提示，不会傻站在原地。
再给你一个生成单元测试的命令模板，这个比较短：
--- description: 为指定文件生成单元测试 argument-hint: <文件路径> --- 为 $1 生成完整的单元测试，要求： - 使用项目的测试框架（见 AGENTS.md 中 common tasks 说明） - 覆盖正常路径、异常路径、边界条件三类场景 - 不 mock 掉核心业务逻辑，除非它涉及 IO 调用 - 测试命名采用 "should ... when ..." 风格 - 生成完毕后运行测试命令，确认全部通过注意我在这里加了"运行测试命令确认通过"这个动作。很多 AI 编码工具生成测试后自己不看结果，你敢让 AI 直接跑一遍，就能把绝大多数低级错误当场暴露。
3.4 第四步：把模板接入团队工作流
模板写完之后，最关键的是分发与更新。模板本身就是项目里的一份代码资产，最标准的做法是放进 Git 仓库，跟着项目走。这样所有 clone 项目的人天然拥有模板。
但有个现实问题：用户级的个人命令模板不会自动跟着项目走。比如我习惯在所有项目里用的/commit命令，就不能指望每个项目都维护一份。我的做法是，把个人通用命令放在~/.claude/commands/下，项目专属命令放在项目仓库中，两边互不干扰。
团队协作场景下，模板的变更建议走 code review 流程。有人改模板就相当于改团队规范，要留痕、要通知。我会在项目的 README 里写一段"如何新增/修改命令模板"的说明，把格式要求和示例代码附上，避免每个人按自己喜好乱写。
4. 高级技巧：让模板从"能用"变成"好用"
模板能跑起来不难，但想让它真正成为团队的效率利器，需要打磨几个细节。这些技巧都是我踩过坑之后总结出来的，价值不比前面的搭建步骤低。
4.1 模板优先级与上下文控制：别让 CLAUDE.md 变成大杂烩
AGENTS.md 不是越详细越好。上下文窗口是有限的，Claude 每读一个字，都会挤占它处理代码的空间。我见过有人把 40 页文档全塞进 CLAUDE.md，结果 Claude 在简单任务上的表现反而变差了，因为注意力被太多无关规则稀释了。
我的经验是：AGENTS.md 控制在 150 行以内，只写高频、硬性、短期不变的规则。那些低频的、需要详细说明的内容，放到独立文档里，用相对路径引用。Claude Code 支持在指令文件里加链接，当任务确实需要时，它可以主动去读那个文档。这样既保证了规范完整，又不拖累日常执行。
4.2 写"禁止"清单比写"应该"清单更有效
这是个非常实用的小技巧。AI 模型对否定指令的执行力，普遍强于肯定指令。原因是"禁止做 X"划出了一条清晰的边界，模型的解码空间立刻缩小；而"应该做 Y"有太多实现方式，模型反而容易自由发挥跑偏。
所以在模板里，我会有意识地大量使用禁止性描述。比如"禁止在 services 层直接操作 req/res"、"禁止在组件里通过 any 断言 props"、"禁止提交包含 console.log 的代码"。每写一条禁止，Claude 的自由度就被约束一截，输出就更接近团队风格。
4.3 给模板设计退出条件与兜底方案
AI 工具最大的毛病之一是不会"停下"。你让 Claude 重构一个函数，它重构完了，可能还顺手把旁边的模块也改了。模板里必须明确写出退出条件。
我在每个任务型模板的末尾，都会加一条兜底说明，比如"完成上述修改后立即停止，不要改动无关文件"或"如果发现改动范围超出指定的文件范围，先停下来向用户确认"。这个只有一句话的设定，能省掉你大量的 review 返工时间。
另外，如果模板里要求 Claude 自主判断请求是否合理，可以加上"若你认为用户请求不明确，先列出至少两条澄清问题再行动"。这句话可以有效避免它瞎猜需求。
4.4 版本管理：给模板打上语义化标签
模板是活的，会持续演进。我个人会给命令模板加语义化版本注释，放在 Frontmatter 之外的地方：
模板版本：v2.1 变更记录： - v2.1 增加安全审查维度 - v2.0 重构输出格式，改为分级清单版本号的意义不在于形式，而在于排查问题时能快速定位。如果之前对话都正常，某天突然输出变得奇怪，先看是不是模板版本变了。模板变更引发的问题通常比代码变更更难排查，留好记录能省很多时间。
5. 常见问题与排查技巧实录
所有模板系统都会遇到这样那样的问题。这一节把我实际遇到的、以及社区朋友反馈过的高频问题整理成一个速查表，并按场景给出排查思路。
5.1 问题速查表
| 症状 | 可能原因 | 解决思路 |
|---|---|---|
| CLAUDE.md 内容完全不生效 | 文件命名或位置不对 | 检查根目录文件名是否是CLAUDE.md或AGENTS.md，且无错误扩展名 |
| 命令模板找不到 | commands 路径不对 | 确认命令文件放在.claude/commands/下，且为.md文件 |
| 参数没有替换 | 使用了错误的占位符 | 检查$1、$2后是否跟了空格，$ARGUMENTS是否写全 |
| 模板内容被完全忽略 | 事件触发时上下文被清空 | 确认该模板是命令调用而非 AGENTS 自动载入，后者只在特定上下文生效 |
| 子目录规范覆盖了根目录规范 | 未理解分层优先级 | 确认子目录规则确实是你的意图，否则删除子目录 CLAUDE.md 中的冲突项 |
| 格式化输出被 Claude 自由改写 | 模板缺少硬性格式约束 | 在模板中用"输出必须严格按照以下格式"并给示例 |
5.2 模板不生效的几个隐蔽原因
第一类隐蔽原因是文件名大小写。有的文件系统不区分大小写，有的区分。CLAUDE.md和claude.md在严格环境下是两个文件，一旦写错就静默失效。建议统一使用大写。
第二类是优先级覆盖。如果你在用户级模板里写了"A 规范"，项目级模板里写了相反的内容，项目级会赢。但如果你在子目录再写一层，又可能变回去。排查这类问题，要按"用户级 → 项目级 → 子目录级"的顺序逐层检查，找出是哪一层覆盖了你的预期。
第三类是路径引用失效。AGENTS.md 里用相对路径链接到 docs 下的文档，如果 Claude 当前工作目录不是项目根目录，链接可能失效。建议统一使用绝对于项目根的路径，或者在模板里写明"以项目根目录为准"。
5.3 上下文膨胀的应对策略
模板越写越多，最后发现每次对话加载的内容也越来越多，响应变慢，准确率下降。这时要果断做减法。我会用"三问法"判断一条规则该不该留在模板里：
- 这条规则高频出现吗？如果一个月才碰一次，撤出模板，放到按需文档里。
- 不写这条规则，后果严重吗？不严重就删，严重就留。
- 这条规则能被其他规则覆盖吗？如果已有更通用的规则能涵盖，就删掉多余项。
用这个方法，我把一个 260 行的 CLAUDE.md 压到了 90 行，Claude 在小任务上的响应速度和准确率都有明显提升。记住：模板的清理频率和代码重构一样，至少每季度一次。
6. 我的最后几条建议
实际操作中我最大的体会是，claude-code-templates 的价值曲线不是线性的，而是阶梯式的。刚引入模板的第一周，你会觉得效率提升了 10%；等到把五六个高频命令全部打磨好、CLAUDE.md 精简到恰到好处时，效率可能是翻倍的提升。关键转折点在于你愿意花多少心思去迭代模板本身。我见过两种极端：一种人写完模板就不动了，半年后模板里全是过时的规范；另一种人天天改模板，改到团队无法适应。我的做法是固定一个节奏：每个月第一个周五，花半小时过一遍模板，看哪些规则可以删、哪些命令缺参数说明、哪些表述让 Claude 产生了误解。这半小时的投入产出比，高得惊人。
另外，想强调一点：模板是为团队服务的，不是给 AI 看的作业。它的最终评判标准只有一个——大家用 Claude Code 干活时是不是更省心了。如果一个模板写得很漂亮，但没人愿意用，那它就是负担而不是资产。所以，新模板上线时，不妨先在小范围试跑一周，收集真实反馈再决定是否全面推广。用起来、改起来、跑起来，你自然能找到最适合自己团队的模板形态。
