1. Claude Code 模板到底是什么为什么值得单独拿出来聊很多人第一次接触 Claude Code 的时候第一反应是这不就是个能读代码、能改文件的终端助手吗然后就开始直接丢需求让它干活。用了一阵子之后你会发现同一个 Claude Code在不同项目里的表现差距可以非常大——在 A 项目里它像个熟悉你代码风格的老同事在 B 项目里它就像个第一天入职、什么都要问的新人。拉开这个差距的就是模板。Claude Code 的模板本质上是一组预先写好的指令文件用来统一告诉模型这个项目是怎么组织的、代码规范是什么、遇到什么情况应该怎么处理。你可以把它理解成给新员工准备的入职手册加工作手册入职手册告诉它公司有多大、部门怎么划分工作手册告诉它提交代码之前要跑哪些检查、线上出问题该找谁。Claude Code 读懂了这些干活的稳定性和质量就会完全不一样。这篇内容适合谁如果你已经用上了 Claude Code但总觉得它不够懂你、每次都要反复纠正它才能干对活那你需要看这篇文章。如果你正准备在团队里推广 Claude Code想让大家的行为风格统一模板更是绕不开的基础设施。我会从模板的分类、目录结构、编写实操、进阶玩法到常见坑位完整过一遍最后给出一套可以直接抄走的模板参考。2. 先认清模板的四种形态别一上来就只盯着 CLAUDE.md很多教程提到 Claude Code 模板张口就是 CLAUDE.md好像有了这一个文件就万事大吉。实际上模板在 Claude Code 里有四层形态它们的加载机制、作用范围和适用场景完全不同。把这四种形态分清楚你才能知道什么时候该用哪个而不是把所有的东西都塞进一个文件里。2.1 CLAUDE.md项目的宪法CLAUDE.md 是 Claude Code 每轮对话开始时都会自动加载的项目记忆文件。它放在项目根目录下作用范围覆盖整个仓库。简单说只要你在项目里启动 Claude Code它就会先读这个文件然后带着文件里的约束去理解你的所有指令。它的特点是常驻每次对话都会生效不管你这个会话是来写代码、查 bug 还是做代码评审。所以 CLAUDE.md 适合放那些通用、稳定、高频的约束——项目技术栈是什么、目录怎么组织的、代码风格习惯、构建测试命令、部署注意事项。我见过不少人把 CLAUDE.md 写成了长篇大论从公司规章制度写到团队协作流程结果模型每次对话都要消耗大量上下文去读这些内容反而影响了对当前任务的专注度。CLAUDE.md 的正确写法是少而准只放那些 Claude Code 每次干活都必须知道的东西。2.2 自定义命令把常用操作固化成快捷键自定义命令就是斜杠命令比如你输入 /reviewClaude Code 就会执行一段预设好的操作流程。它们放在 .claude/commands/ 目录下使用绝对路径的还是项目级命令取决于放在哪里。这个形态解决的是高频重复操作的问题。比如我们团队每天都要做代码评审以前每次都要手动输入请帮我看一下这个 PR 的改动注意检查边界条件和错误处理按严重程度分类反馈字多且每次表述都不一致。把它写成一个 /review 命令之后输入三个字符就搞定了评审的标准也统一了。和 CLAUDE.md 相比命令是按需触发的。你不调用它它就不消耗上下文。这非常关键——不是所有东西都需要常驻记忆很多标准流程只需要在用到的时候调出来就行。2.3 子代理为特定任务准备的专家分身子代理是 Claude Code 3.7 之后引入的能力本质上是在主对话之外定义一个拥有独立系统提示词的专家角色。在 Agent SDK 的语境里你甚至可以为它指定专属的模型参数。子代理的模板文件放在 .claude/agents/ 目录下每个 Markdown 文件定义一个角色。和自定义命令的区别在于命令只是一段指令执行的时候还是主模型在干活子代理则是一个独立的全新上下文窗口它只带着自己的角色设定和任务描述去处理工作处理完把结果汇报给主对话。这个设计很聪明它解决了上下文隔离的问题。比如你要让 Claude Code 审查代码安全性如果直接在主对话里做它会带着整个项目的背景和当前任务的各种细节去思考容易受干扰。但如果你派一个 security-auditor 子代理去它只专注安全检查这一件事产出质量会高很多。2.4 模板目录整套复用与分发的打包层除了上面三种单文件形态还有一种统称意义上的模板——把 CLAUDE.md、commands、agents、hooks 组合成一个完整的模板目录像项目脚手架一样新建项目时直接拷进去就能用。这种形态适合团队标准化和开源分享。比如你的团队统一用 TypeScript React 微前端架构那你可以做一套完整的 Claude Code 模板包新建前端项目的时候整套复制过来所有成员的 Claude Code 行为就从各自为战变成了一个模子刻出来的。我认为这是模板最有价值的形态因为它把单点配置升级成了工程化基础设施。后面我会专门讲怎么搭建这样一套可复用的模板目录。3. 从零搭建模板库目录结构、文件编写与参数设计说了这么多类型现在落到实操。我会用一个真实的场景来演示假设我们要为团队的前端项目搭建一套 Claude Code 模板库包含 CLAUDE.md、自定义命令和子代理三层结构。3.1 先规划目录结构再动手写文件一套完整的模板库目录结构大概是这样的project-root/ ├── CLAUDE.md ├── .claude/ │ ├── commands/ │ │ ├── review.md │ │ ├── test.md │ │ └── commit.md │ ├── agents/ │ │ ├── code-reviewer.md │ │ └── bug-hunter.md │ └── hooks/ │ └── pre-tool-use.md这个结构的原则是各司其职CLAUDE.md 放通用约束commands 放按需操作流程agents 放专项专家角色hooks 放自动化拦截逻辑。你不需要一上来就全建建议按需添加用到一个领域再加一个文件避免前期过度设计。3.2 写一份不废话的 CLAUDE.mdCLAUDE.md 的核心是精准不是全面。我给你的参考结构是四段式# 项目概览与命令 ## 项目概览 - 项目名称与一句话定位 - 核心技术在技术栈树前端 React 18 TypeScript 5后端 Node.js 22 Fastify数据库 PostgreSQL 16 - 目录结构摘要src/ 业务代码libs/ 可复用模块tests/ 单元测试 ## 常用命令 - 安装依赖: npm install - 启动开发服务: npm run dev - 运行测试: npm test - 构建生产包: npm run build - 代码检查: npm run lint npm run typecheck ## 代码规范 - 函数必须有明确的输入输出类型禁止使用 any - 组件使用函数式写法 hooks不使用 class 组件 - 提交信息遵循 conventional commits 规范 ## 注意事项 - 修改数据库 schema 后必须生成迁移文件 - 删除代码前先全局搜索确认没有残留引用 - 涉及支付、权限相关改动必须补充安全测试用例注意我特意没写团队文化日报周报这些东西。CLAUDE.md 只服务于一个目标让 Claude Code 在这个项目里的每一次操作都符合项目的基本规则。冗余内容只会稀释它真正的约束力。写完这个文件之后你可以做一次快速验证启动 Claude Code直接问它这个项目的测试命令是什么它应该能准确回答。如果它答错了或者答得含糊说明你的文件写得太含糊需要改得更具体。3.3 自定义命令怎么编写参数怎么设计命令文件是 Markdown 格式包含 YAML frontmatter 和正文两部分。frontmatter 里定义命令的元信息正文就是实际操作指令。给你看一个代码评审命令的完整示例--- description: 对当前分支的改动进行代码评审按严重程度输出问题列表 argument-hint: 可选指定评审关注点如安全、性能、可读性 --- 对当前分支相对于主分支的改动进行代码评审。 评审流程 1. 先运行 git diff main...HEAD 拿到完整改动列表 2. 从改动中识别出核心逻辑变更逐一分析 3. 重点关注边界条件处理、错误分支遗漏、资源未释放、日志缺失 4. 对每个问题标注严重程度阻塞/重要/建议并给出修改方案 关注点无论则按以上通用维度评审 如果有用户输入优先围绕用户指定的维度展开。 输出格式 - 头部归纳本次改动涉及的功能模块 - 按严重程度排序每类下用列表输出问题 - 每个问题包含文件位置、代码片段、问题描述、修改建议这个文件里有三个关键设计第一argument-hint 告诉用户这个命令可以接收可选参数第二正文里明确规定了评审流程模型就会按照这个流程一步步执行而不是自由发挥第三输出格式的要求保证了每次评审结果的结构化方便团队成员浏览。命令启动之后模型会先读取这个 Markdown 文件然后按照里面的指令执行。所以你的指令写得越可操作执行效果就越稳定。别写请认真评审这种话要写先执行 xx再分析 xx最后按 xx 格式输出。3.4 子代理模板的编写要点子代理文件的核心是角色定义和能力边界。我给你看一个代码评审子代理的例子--- name: code-reviewer description: 资深前端代码评审专家专注发现逻辑缺陷与安全隐患 tools: Read, Grep, Glob model: sonnet --- 你是一位拥有十年经验的前端架构师专注代码评审。 你的工作原则 1. 只评审代码质量问题不讨论业务需求是否合理 2. 从调用链的角度分析问题不止看单个函数 3. 对每个问题给出可操作的修复建议禁止说空话 4. 发现数字敏感信息相关代码时额外标注安全风险 工作流程 - 先理解改动文件的调用关系 - 再逐文件审查 - 最后输出一份结构化评审报告注意看 frontmatter 里的model字段这是子代理一个很实用的特性。你可以让简单的子代理用速度更快的模型跑让复杂的分析任务用更强模型跑这样既能保证质量又能控制成本。agents 目录的子代理文件很容易理解你在主对话里输入 code-reviewer 来调用它它会在自己独立的上下文里处理任务。子代理的 System Prompt 就是这个 Markdown 文件的内容所以你的描述会直接影响它的表现。4. 进阶玩法Hooks 自动化、条件模板与团队分发基础模板搞定之后接下来是真正拉开体验差距的进阶内容。这里要说的不是怎么继续堆文件而是怎么让模板体系动起来以及怎么在团队里规模化落地。4.1 用 Hooks 做自动化拦截Hooks 是模板体系里最容易被忽视、但最能体现工程化水平的部分。它允许你在 Claude Code 的某些生命周期事件上挂脚本比如每次工具调用之前、每次会话结束之后。一个很典型的场景是规范代码格式。你在 CLAUDE.md 里写了代码必须通过 eslint但模型偶尔还是会忘。这时候可以加一个 hook在 Claude Code 每次执行写完文件工具之前自动跑一下 lint发现问题就拦截下来提示模型修正。--- hook-name: pre-lint-check --- 当 Claude Code 准备写入或修改 .ts/.tsx 文件时先执行 npm run lint -- 目标文件路径如果 lint 失败将错误信息反馈给主对话要求修正后再重新写入。Hooks 的最大价值在于它不依赖模型自觉。模型再聪明也有注意力漂移的时候但 hooks 是确定性的拦截逻辑只要挂了就一定会执行。把那些必须做、容易忘的操作交给 hooks比在 CLAUDE.md 里反复强调一百遍都管用。4.2 条件模板同一个文件不同分支表现Claude Code 的模板文件支持一定的条件语义。你可以在文本里写如果你想做的事属于 A 情况请按以下步骤……模型会自己判断当前任务属于哪条分支。这不是编程语言里的 if-else但对模型来说已经够用了。比如在 CLAUDE.md 里写## 按场景处理 - 如果改动涉及数据库迁移必须先生成迁移文件并在本地数据库执行验证通过后才算完成 - 如果改动涉及第三方 API 调用需要检查超时配置与错误重试逻辑 - 如果改动涉及对外接口需要同步更新接口文档与类型定义这种写法把项目里不同领域的特殊规则放进了同一个模板模型会根据任务内容自动匹配。好处是你的模板文件数量不会爆炸——不需要为每个领域维护一份独立的 CLAUDE.md一份文件里写清楚分支规则就行。4.3 团队分发模板怎么变成基础设施当你的模板自己用着顺手了接下来就是团队复制的问题。我给两种分发路径。第一种是硬拷贝把整套模板目录打包通过内部文档或脚手架工具分发给成员。这种方式简单直接但有一个问题——模板后续更新了成员本地的不一定同步。适合小团队或者刚开始推的阶段。第二种是模板生成器写一个命令行工具命名为create-claude-config之类的运行后根据用户输入生成定制化模板。团队技术栈不同生成器的前端参数和后端参数也不同。这个路径适合有一定工程能力的团队把模板变成公司内部的代码生成器长期维护成本更低。无论哪种方式有一点逃不掉模板必须持续迭代。我见过太多团队模板放出去三个月没动过项目技术栈都升级换代了模板还在教模型用旧方案。让这个体系里有专人负责维护定期根据成员反馈和实际使用效果更新模板内容。5. 实操中踩过的坑与对应解法模板这个东西看起来就是一个 Markdown 文件好像没什么技术含量。但真正用起来坑多得很。我把自己在实际操作中遇到的高频问题整理成一张速查表每个问题后面附上我验证过的解法。问题现象根本原因解法模板内容完全没生效文件路径或文件名错误检查文件是否在项目根目录的 CLAUDE.md或在 .claude/ 子目录下文件名必须是规范大小写模型总是不按模板执行模板指令太空泛模型不知道如何落地把保持代码整洁改成提交前必须执行 npm run lint输出无 error 才算通过模板文件太冗长每次对话响应变慢CLAUDE.md 常驻上下文消耗太大将长内容拆分通用约束放 CLAUDE.md低频操作流程放 commands复杂专家角色放 agents自定义命令找不到命令文件路径错误或 frontmatter 缺字段优先检查 .claude/commands/ 下的 .md 文件名不带 .md 后缀直接输文件名调用子代理行为不稳定角色描述不够具体缺少工作流程约束在子代理模板里写清工作原则 工作流程 输出格式三件套缺一不可不同成员的模板产生冲突根目录模板、用户级模板加载优先级不清晰明确优先级项目 CLAUDE.md 父目录 CLAUDE.md 用户级 CLAUDE.md统一模板来源模板更新后模型仍用旧行为Claude Code 缓存了旧会话的上下文模板变更后新开会话旧会话不会重新加载模板5.1 上下文膨胀模板体系的隐形杀手这是我最想强调的一个坑。CLAUDE.md 是每轮对话都常驻的内容越多模型用于思考当前问题的注意力就越少。有人测试过把 CLAUDE.md 写到 8000 字之后模型对当前任务的理解和执行质量会明显下降因为它脑子里塞满了背景资料。我的经验值是项目级 CLAUDE.md 控制在 300-500 行以内超过这个量就要开始拆分。拆分的顺序是先把操作流程类的拆到 commands再把需要专家视角的内容拆到 agents最后只留真正的宪法性内容在 CLAUDE.md 里。5.2 模板万能论的误判还有一个认知层面的坑以为模板写得越详细模型表现就越好。实际恰恰相反。模板的核心是给模型提供约束和边界而不是替它把每一步都安排好。如果你的模板详细到第一步打开这个文件第二步找到那个函数那模型出错的概率反而更高——因为实际代码和你的描述之间总有偏差模型会被你那些过时的细节误导。好的模板应该管住方向和标准不碰具体路径和实现。比如规定改动公共接口必须同步更新调用方而不是规定改了 utils/api.ts 之后要去 utils/types.ts 里加一段类型。前者是规则无论代码怎么演化都有效后者是快照代码一变就失效。5.3 模板调试的实用套路模板出了问题怎么排查我的套路是三步走。第一步单独测试新开会话只问模板相关的问题确认它是否能正确执行。第二步去掉无关变量如果你同时改了模板和代码模板不生效了先恢复代码排除干扰。第三步用命令手动触发自定义命令可以直接在终端里输入命令名触发会比自然语言对话更容易暴露问题。调试时有一个小技巧直接在对话中让 Claude Code总结你当前掌握的关于本项目的规范和命令它会从已加载的模板中把关键信息复述出来。你一眼就能看出它到底读到没读到、读对了多少。这个方法我强烈推荐每次改完模板先跑一遍这个验证能省下大量反复对话的调试时间。6. 一套可直接参考的模板范例Web 项目通用型最后我放一套自己在实际项目中用着很顺的模板目录结构你可以直接参考着搭建。这套模板针对的是TypeScript Web 全栈项目但改动一下技术栈关键词就能适配其他场景。# CLAUDE.md项目根目录 ## 项目信息 - 全栈 TypeScript 项目前端 React Vite后端 Fastify数据库 PostgreSQL - 代码目录apps/web前端、apps/api后端、packages/shared共享类型与工具 ## 常用命令 - 安装依赖: pnpm install - 启动全部服务: pnpm dev - 运行全部测试: pnpm test - 类型检查: pnpm typecheck - Lint: pnpm lint ## 开发规范 - 所有跨端共享类型放在 packages/shared/src - 错误处理使用统一 AppError 类禁止裸 throw string - 组件目录结构遵循 feature-based 模式 - 提交信息遵循 conventional commits ## 按场景处理 - 修改数据库 schema 后生成迁移文件并本地验证 - 新增 API 端点后同步更新 OpenAPI 文档与前端类型 - 修改鉴权逻辑时必须补充权限边界测试用例# .claude/commands/review.md --- description: 对当前分支改动进行代码评审 --- 对当前分支对比 main 分支的改动执行评审。 流程 1. git diff main...HEAD 拿到改动列表 2. 分析核心逻辑变更 3. 检查边界条件、错误处理、性能问题 4. 按 阻塞/重要/建议 三级输出问题清单每个问题给出修改方案# .claude/agents/api-designer.md --- name: api-designer description: API 设计专家专注于设计清晰、安全、可扩展的接口 tools: Read, Grep, Glob --- 你是 API 设计专家负责评审和设计 RESTful 接口。 工作原则 1. 路径命名遵循 REST 资源语义不使用动词路径 2. 对所有输入做严格的类型校验和边界验证 3. 分页参数必须包含 limit/offset并设置上限 4. 错误响应统一使用 { code, message, details } 结构 输出要求 - 对每个端点列出请求参数、校验规则、成功与失败响应示例 - 对设计不合理处直接给出修改后的方案这三个文件各司其职CLAUDE.md 管全局约束review 命令管代码评审流程api-designer 子代理管接口设计专项任务。你从这套结构起步根据自己项目的实际情况增删内容会比从零开始写要快得多。这个模板体系的扩展方向也很多。你可以加一个 /commit 命令规定提交信息的生成规则可以加一个测试专家子代理专门负责补测试用例还可以加 hooks在写入文件时自动跑类型检查。无论怎么扩展记住那条核心原则模板是给模型划边界的不是替你干活的。边界划清楚剩下的事交给模型自己发挥它的表现会超出你的预期。