我记得第一次把 Claude Code 引入团队时最直观的感受是一个新项目从零开始它确实能写代码但总在同一个地方反复绕圈子——不知道项目结构、不记得已有约定、理解不了某些看似奇怪的代码决策每次都要我重新解释一遍。后来我建了自己的claude-code-templates模板库把项目背景、规范、常用命令和子代理全部沉淀成模板这问题才彻底解决。模型本身是你的员工而 templates 就是员工入职手册手册写得越清楚干活越靠谱。这篇文章会从模板的类型、写法、落地到排坑完整讲清楚我实际怎么用它。1. 先搞清楚Claude Code 模板到底在解决什么问题Claude Code 本质上是一个跑在终端里的 AI 编程助手它能读取代码库、找文件、改代码、执行命令、跑测试甚至操作 git 分支提交。能力很强但它的工作质量严重依赖上下文质量。你让它“帮我修一下登录超时的 bug”它要自己翻代码找问题同一段逻辑可能看三遍才看懂中间还会产生各种错误假设。模板就是用来解决这个问题的。它把项目里稳定的、需要反复交代的信息提前固化下来让每次会话开始模型就能拿到。这些信息包括项目是干什么的、技术栈和框架是什么、目录如何组织、用哪些命令跑测试、代码风格有什么约定、有哪些环境变量和脚本甚至还有“不要动某个模块”“某处历史包袱是什么”这类只有老成员才知道的隐性知识。模板又不止 CLAUDE.md 一个文件。一套完整的模板体系通常包括项目说明文件、自定义斜杠命令、子代理定义、自动化钩子以及一套可以初始化新项目的脚手架文件。它们组合起来不只是为了一次对话更顺畅更重要的是让团队里所有人都能获得同等的 AI 生产力。新人来了不熟悉业务拉下来模板就能开始干活不同成员问同一个问题的路径一致输出结果也趋于稳定。对我这种要做技术管理的人来说模板就是低成本的团队共识落地器。适用人群其实很广独立开发者想减少重复解释可以单人使用中小技术团队想统一 AI 工作方式可以做内部共享模板维护多个项目的人更需要一套可复制的速用配置避免每开一个新仓库就从零调教一遍。下面我把实际用到的模板分类拆开来讲。2. 五大类模板按需取用2.1 项目说明模板CLAUDE.md 是灵魂CLAUDE.md 是整个模板体系的核心。它在项目根目录下Claude Code 每次启动时都会自动读取相当于给模型灌注项目记忆。很多人以为它就是给 AI 看的 README这个理解太浅了。README 面向人类强调“如何用这个项目”CLAUDE.md 面向 AI强调的是“在这个代码库里做事时应该遵守什么”。我在 CLAUDE.md 里通常会放五类内容项目角色设定告诉模型它在这个项目里充当什么角色比如“你是这个 Node.js 服务的资深维护者”。当前任务状态最近几次会话在做什么、下一步待办是什么。架构和目录导航模型最需要的索引避免它盲目翻文件。常用命令install/test/lint/build 分别是啥带参数带环境变量。硬性注意事项哪些文件不要改、哪些操作不能做、有哪些容易踩的坑。它相当于给模型划定了做事的边界和路径。有了它同一个代码库在不同人手上用 Claude Code 跑任务行为一致性会高很多。2.2 命令模板把常用操作变成斜杠命令Claude Code 支持斜杠命令在对话里输入/review、/test这样触发一段固定逻辑。这些命令本质上是放在.claude/commands/目录下的 Markdown 文件文件名就是命令名文件内容就是告诉模型该干什么。命令模板最大的价值是数字化团队流程。比如我们团队有代码评审规范口头解释总是漏这漏那写成一个/review命令模板后每次点一下模型就会按模板里写的检查清单逐项过代码。命令模板还可以带参数比如/fix node指定要修某个模块实现和自然语言交互的固定组合。日常我维护的命令模板有Init初始化项目说明、Test按模块跑测试并汇总覆盖情况、Review按团队标准审查代码、Changelog基于 git log 生成变更日志。这些模板从本质上把“怎么指挥 AI”固化成了团队资产新人不用知道怎么提问最好只需要知道用哪个命令。2.3 子代理模板拆解复杂任务的执行单元简单的任务直接在主对话里做就好但复杂任务如果一股脑全丢给 Claude Code它会因为上下文太长而前后矛盾。子代理subagent模式是我目前很依赖的模板类型。它运行在独立上下文中有自己的任务目标和约束适合隔离某个特定领域。典型做法是在.claude/agents/下定义子代理文件。比如我常定义这几个debug-agent.md专门定位 bug只做排查输出结论不直接改代码。test-agent.md负责写测试和跑测试专注覆盖率。refactor-agent.md只做重构在一段任务中维护函数行为不变。每个子代理模板都带name、description和一段明确的“你做什么你不做什么”。这样主模型在工作时会把适合的任务委派给子代理结果再收回来整合。它的好处是隔离上下文、控制范围避免一个大任务里模型在“改代码”和“查问题”两个角色间反复横跳。2.4 钩子模板在关键节点自动执行预设动作钩子是 Claude Code 在特定事件触发时自动执行的脚本或命令事件包括每次工具调用前后、会话开始时、收到通知等。钩子模板的意义是把安全性和规范性从“请模型自觉”变成“由机制强制”。举个例子我在自己的模板库里放了一个pre-tool-check.sh在模型执行删除类工具前强制确认目标文件路径还会在 PostToolUse 阶段检查生成的代码有没有明显的调试残留比如console.log和debugger一旦发现就自动拦截并提示。这样等于给 AI 的操作加了一层保险丝。钩子配置一般写在.claude/settings.json里或者用claude命令交互配置。模板文件里我放的是可复用的 JSON 片段和 shell 脚本新项目拷贝时直接改路径就能用。它不像 CLAUDE.md 那样能被模型“记在心里”解决的是边界问题属于必须依赖硬机制兜底的场景。2.5 项目脚手架模板初始化即就绪最后一类模板是项目脚手架。它把前面所有内容打包成一个初始化模板仓库新项目开始时就拷贝或者拉取一套配置直接落地。这个模板仓库的内容包括标准的 CLAUDE.md 结构、.claude/commands/下全部命令、.claude/agents/下的子代理定义、.claude/settings.json的钩子配置以及一套.gitignore和项目基础目录结构。对我来说脚手架模板的意义不是每次省那几分钟而是保证团队所有新项目都站在同一个起点上不会因为某个人忘了配而漏掉关键约束。3. 拿得出手的 CLAUDE.md 模板长什么样空谈类型没意思我直接贴一份我目前在用的 CLAUDE.md 模板它是从多次实战里迭代出来的版本。你可以直接拷走改。# 项目角色 你是一名资深的 Node.js 全栈工程师也是本项目的核心维护者。 项目运行在 Node 20 TypeScript 5 Express 4 环境下。 # 项目概述 本项目是一个面向中小商家的库存管理系统提供商品管理、订单流转、 库存预警、报表导出四个核心模块。业务特点是数据一致性要求极高 任何库存数量的变更都必须通过 service 层禁止直接操作数据库。 # 架构与目录导航 src/ api/ # HTTP 路由层只做参数校验和响应组装 service/ # 业务逻辑层库存变更、订单流转的核心代码 repository/ # 数据库访问层使用 TypeORM shared/ # 公共类型、常量、工具函数 config/ # 环境变量读取和配置校验 scripts/ dev.sh # 本地开发启动脚本 test.sh # 跑单测 覆盖率统计 seed.sh # 种子数据初始化 tests/ unit/ # 单元测试按模块路径镜像 src e2e/ # 端到端测试使用 Playwright # 常用命令 - pnpm install 安装依赖不要使用 npm - pnpm dev 启动开发服务默认端口 3100 - pnpm test 运行单测参数 --watch 可进入 watch 模式 - pnpm lint 跑 ESLint 代码检查PR 合并前必须通过 - pnpm build 执行 tsc 编译产物输出至 dist/ # 代码规范与约束 1. 方法命名统一使用 camelCase常量使用 UPPER_SNAKE_CASE。 2. service 层必须显式声明事务边界库存扣减使用乐观锁 version 字段。 3. 所有 API 响应统一走 shared/response.ts 里的 wrapOk / wrapErr 封装。 4. 数据库表结构变更前必须同时提供 migration 文件和 rollback 脚本。 5. 日志使用 pino禁止在代码中直接 console.log。 6. 错误码统一维护在 shared/errors.ts禁止硬编码。 # 绝对不要做的事 - 不要直接修改 src/repository 下的查询来绕过 service 层校验。 - 不要改动 legacy/ 目录下的旧版订单模块该模块已被新逻辑替换。 - 不要删除或修改 .env.example 中已有的环境变量名。 - 不要在未跑通 e2e 测试的情况下标记订单流程任务完成。 # 最近更新与待办 - [2025-06-01] 完成库存预警模块的重构旧逻辑已迁移至 service/inventory。 - [TODO] 报表导出支持按时间范围过滤当前只支持全量导出。我特别想强调两个容易忽略的要点一是“绝对不要做的事”最好单列它比“应该做什么”更能减少破坏性行为二是“最近更新与待办”要随项目推进持续更新让模型始终知道当前状态避免它基于一个月前的过期认知做决策。3.1 头部信息与角色设定很多人写 CLAUDE.md 一上来就是技术栈列表但没有角色定义。我觉得角色设定相当重要因为同样的代码库“资深维护者”和一个“刚接手的新人”处理问题时的方式完全不同。角色设定明确后模型在遇到模糊情况时会倾向于按这个角色的经验做判断。示例里我在第一段就写了角色、语言和核心经验。这个设定不一定要多长但需要包含两个关键信息技术身份和项目身位。技术身份决定它用什么层次的语言和你交流项目身位决定它对代码的熟悉度和修改权限。比如“核心维护者”就可以允许直接重构“外部审阅者”则应该优先提问而不是动手改文件。3.2 架构说明与目录导航模型在代码库里找文件是很费上下文的操作如果没有目录索引它可能遍历几十个文件才定位到目标。所以我把目录结构直接写进 CLAUDE.md并附上每层的职责说明。这相当于给模型一张地图它看到问题就能大致推算代码可能在哪个目录。这里有个技法标注出“重要且不常见”的目录比如legacy/、scripts/因为模型容易误判这些目录的作用。我见过很多次它试图在scripts/里找业务逻辑就是因为没在图里说明。你可以在导航中直接注明“scripts 只放运维脚本不含业务代码”模型就会少走弯路。3.3 命令、代码规范与禁忌清单命令部分要写全尤其是一些冷门但有必要的操作比如测试时需要指定环境变量、跑某个迁移脚本前要启动 Redis。模型如果没有准确命令容易自己脑补一条然后对着一个不存在的脚本报错浪费大量时间调试。规范部分不是越多越好只写“不满足会导致返工”的硬性规范。我一般控制在五到十条重点覆盖命名、分层边界、事务、日志、错误处理这些高频破坏点。禁忌清单单独放一节每条都要像示例那样具体到一个动作和一个对象而不是“注意代码质量”这种没营养的话。3.4 增量维护让模板真正活起来CLAUDE.md 不是写一次就完的它应该随项目演进不断维护。我养成了一个习惯每次 Claude Code 完成一段重要工作时我都会让它把变更的关键信息和新增的注意事项补进 CLAUDE.md然后审阅合并。实际操作中我会对模型说“请把这个会话中发现的隐藏规则追加到 CLAUDE.md更新最近更新章节并移除已经不再适用的条目”。这样模板会像一个活文档一样积累团队的经验。如果只是最初写一版之后不管过两三个迭代它就会和真实项目脱节反而误导模型。4. 实操从零搭建你自己的 templates 仓库4.1 仓库目录设计我的模板库目录结构长这样claude-code-templates/ project/ CLAUDE.md.tpl .claude/ settings.json commands/ init.md test.md review.md fix.md changelog.md agents/ debug-agent.md test-agent.md refactor-agent.md hooks/ pre-tool-check.sh post-tool-review.sh scripts/ init-project.sh update-from-project.sh docs/ usage-guide.mdproject/里放的是模板内容后缀用.tpl区分模板文件和实际文件scripts/放两个脚本一个初始化项目一个把项目中实际迭代产出的优秀配置回收到模板库。这套结构支持了多个项目的统一管理。4.2 核心模板文件内容示例命令模板其实就是带 frontmatter 的 Markdown。下面是我常用的/review命令文件内容--- description: 按团队规范审查当前分支代码 argument-hint: [可选] 指定要审查的文件或目录 --- 执行代码审查任务按以下步骤进行 1. 先运行 git diff main...HEAD 获取当前分支改动。 2. 对每个改动文件检查如下维度 - 是否有未处理的边界条件和错误分支 - 是否有安全问题SQL 注入、越权访问、敏感信息硬编码 - 是否符合 CLAUDE.md 中定义的代码规范 - 是否有明显的性能问题比如循环内查询数据库 3. 输出审查报告按「必须修复」「建议优化」「可选调整」三级分类。 4. 如果 argument-hint 提供具体文件则只审查对应文件。命令模板的核心是“步骤要写死”。除了个别需要动态判断的环节我尽量让模型按固定顺序执行。这样执行结果可预期多人用时结果也稳定。命令文件里还可以让模型自我约束比如要求“未运行测试不得给出‘没问题’结论”。4.3 落地到项目两种注入方式把模板应用到实际项目我试过两种方式直接复制和符号链接。直接复制是最简单可靠的方式。执行scripts/init-project.sh 目标项目根目录脚本会把模板目录里的文件复制过去并根据项目名替换一些占位符。好处是不依赖文件路径项目里可以看到所有配置改动自由坏处是后续模板更新不能自动同步到已建项目。符号链接则相反适合想把模板作为中央配置统一维护的场景。把claude-code-templates/project/.claude软链到项目的.claude目录模板更新后所有项目自动生效。但这样配置改动全部集中在模板仓库不同项目之间的差异化需求不好处理。我目前采用混合方案CLAUDE.md 用复制因为每个项目差异大必须独立演化.claude/commands/和settings.json用符号链接或复制混合常用命令同步有特殊需求的项目单独覆盖。关键是每季度做一次模板回刷把项目中新增的优秀命令合并回模板库。4.4 团队共享与版本控制模板仓库本身就是一个 Git 仓库这是团队协作的基础。每个模板文件要有明确的边界和变更历史比如命令模板就是命令不要混入业务代码片段。团队里都可以提 PR但合入前要有一个人统一 review避免模板无限膨胀。我会把docs/usage-guide.md写得非常基础包括“如何安装模板”“怎么跑初始化脚本”“遇到问题时怎样提 issue”。这份文档面向的是对 Claude Code 不太熟的新成员按步骤做就能搭起环境。版本控制上我用 tag 标记兼容版本比如v1.0、v1.1需要稳定性的项目可以锁版本使用。5. 实战案例一个 Node.js 项目如何用模板提效5.1 初始化流程用我刚搭的模板库初始化一个 Node.js 库存系统时流程很短。我先克隆模板仓库然后跑脚本git clone gitgithub.com:yourname/claude-code-templates.git cd claude-code-templates ./scripts/init-project.sh ../inventory-system脚本做的事情很简单把project/CLAUDE.md.tpl复制为新项目的CLAUDE.md把.claude/整个复制过去再用sed替换掉模板里的占位符比如项目名和端口号。最后它会检查目标项目的package.json把实际 scripts 里的命令自动补到 CLAUDE.md 的常用命令章节这样模型拿到的命令和项目真实命令完全一致。这个过程大约一分钟。之后我直接在项目目录启动claude它第一时间读到 CLAUDE.md就能准确说出这个项目的技术栈、架构和规范。这比刚建一个纯空项目然后从零和 AI 对话要高效得多。5.2 自定义命令让 CI 前检查变省心我在这个项目里最常用的是自己写的/check命令。这个命令把 CI 的关键步骤全部串起来在提交 PR 之前让 Claude Code 自己跑一遍。命令内容大概如下--- description: 提交前完整检查lint、单测、构建、关键路径 --- 严格按照以下顺序执行预提交检查 1. 执行 pnpm lint如果有错误则修复后重新运行直到通过。 2. 执行 pnpm test输出测试结果和覆盖率。 3. 执行 pnpm build确保 TypeScript 编译无错误。 4. 核对 git status列出本次未提交的改动确认没有意外修改。 5. 若所有步骤通过输出「预检查通过」否则报告具体失败项。在没有这个命令之前我常常忘了让模型检查覆盖率或者在 lint 失败时就让它直接提交。现在一个命令全搞定而且每个步骤的顺序是硬性的。命令里还隐含了一条要求如果修复了 lint 错误必须重新跑一遍 lint而不是修完就往下走。这类细节如果靠自然语言临时交代很容易遗漏。5.3 效果对比我记录过一段时间同一类需求“新增一个商品分类筛选接口”使用模板前后的差异很明显。维度没模板时使用模板后首次理解代码结构时间需要多轮文件探索约 15 分钟直接从 CLAUDE.md 获得索引约 3 分钟是否符合分层规范偶尔绕过 service 层需要人工拦截严格按仓库/服务/API 分层基本无需返工是否记住禁止事项容易触摸 legacy 目录造成误改极少触发模板中有明确警告提交前检查质量时跑时不跑覆盖率不达标统一走 /check输出稳定新人上手成本需要老成员陪着解释项目约定读一遍模板即可独立开工从数据看效率提升有出入但真正让我决定坚持下去的是稳定性。不用模板时Claude Code 像换了个人似的时好时坏用了模板后它的行为模式基本固定我可以在经验积累上持续改进模板而不是每次都要从头调教多个不确定的变量。6. 常见问题与排查实录6.1 模板生效还是没生效我刚开始用的时候最常遇到的情况是改了 CLAUDE.md但它好像没按新规则执行。首先得确认模型确实读到了它。Claude Code 在启动时会加载规则但更长对话中它也可能因为上下文里的其他信息而忽略某些旧规则尤其是新规则和它之前的行为习惯冲突时。我的排查步骤先看 CLAUDE.md 是不是真的在项目根目录文件名大小写是否正确再确认没有其他层级规则覆盖它比如~/.claude/CLAUDE.md位于用户主目录存在时它的优先级和项目文件合并策略会让模型困惑最后在对话里直接问它“你读到的项目规范是什么”让它复述关键条目。如果复述不全说明加载可能有问题或模板内容太冗长被截断这时需要精简模板。6.2 CLAUDE.md 过长反而拖累上下文模板写得越来越好之后容易膨胀成一部百科全书这是另一个极端。Claude Code 的上下文窗口是有限的CLAUDE.md 太长会挤占模型处理任务的空间。而且模型对超长说明书不是全盘吸收它可能会忽略后半部分内容。我的经验是把 CLAUDE.md 控制在 300 行以内优先放最高频和最关键的信息低频细节放到命令模板或子代理中。比如数据库迁移规范不必写在 CLAUDE.md 里可以放到/migrate命令模板中用到时才加载。如果确实需要保留长文可以把长文拆成docs/architecture.md然后在 CLAUDE.md 里用一句“架构细节见 docs/architecture.md并在做跨模块改动前阅读该文件”来引导。6.3 命令找不到或权限异常自定义命令不生效大多是路径问题。命令文件必须放在正确目录项目级是.claude/commands/用户级是~/.claude/commands/文件名去掉扩展名就是触发命令。比如review.md对应/review。文件编码和 frontmatter 格式也有可能出问题我就踩过 frontmatter 里漏了---结尾导致整个文件被当作普通内容的坑。还有一类坑是命令文件里的脚本执行权限。钩子脚本要执行 shell 时需要检查文件是否有可执行权限或者调用方式是否正确。我一般在settings.json里写脚本路径时会先手动执行一遍确认脚本本身没问题再配置钩子避免把问题混在一起。6.4 跨平台兼容性坑如果团队成员混用 macOS 和 Windows模板里的脚本研究就会遇到坑。最常见的是路径分隔符、shell 语法以及命令差异。grep、sed这类在 mac 上可用但 Windows 默认终端可能不支持。我的做法是规范模板中的脚本统一走node写逻辑因为项目一定装 Node用 Node 脚本写跨平台兼容性最省事。另一个细节是行尾符。Windows 的 CRLF 可能导致模板脚本在 mac 或 Linux 上执行时报错“坏的解释器”。我把模板仓库的.gitattributes设置为*.sh text eollf强制脚本保持 LF 行尾避免这类玄学问题。模板的全局设置里也尽量用环境变量而不是硬编码路径。最后再分享两个小技巧实际维护模板一年下来我最大的体会是模板不是一个静态产物而是一个不断沉淀经验的地方。遇到问题解掉之后我会顺手把原因写进 CLAUDE.md 的“绝对不要做的事”里让同类问题不再出现第二次。这个习惯带来的收益比任何一次性的配置都大。另外如果团队里有多个前端项目、多个后端服务我建议把公共模板做成基础层再为每个项目建立继承层。基础层放语言规范、通用命令和通用钩子继承层放项目特有架构和业务约定。两者通过不同目录管理先读基础层再读继承层既能统一又不牺牲灵活性。这大概就是 templates 的价值——把经验沉淀下来让每一次 AI 协作都不需要从零开始。
