如果你团队里已经有人在用 Claude Code 写代码大概率会遇到这样的场景同一个项目三个人三条对话风格。A 让 Claude 生成的函数带完整的类型注解和 JSDocB 忘了加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/modelsPrisma 数据模型与查询封装 ## 编码规范必须遵守 1. 后端接口返回结构统一为 { code: number, message: string, data: any } 2. 禁止在 routes 里编写业务逻辑一律走 services 3. 前端组件统一使用组合式 APIsetup 语法糖 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 干活时是不是更省心了。如果一个模板写得很漂亮但没人愿意用那它就是负担而不是资产。所以新模板上线时不妨先在小范围试跑一周收集真实反馈再决定是否全面推广。用起来、改起来、跑起来你自然能找到最适合自己团队的模板形态。