★ FEATURED ARTICLE 我刚开始用 Claude Code 的时候跟大多数人一样把 CLAUDE.md 当成一个“可写可不写的项目简介”。直到有天下午我发现自己在五个不同项目里反复粘贴同一段话——“请先读一下 package.json 和 src 目录结构然后再按我们团队的规范写代码”——才开始觉得哪里不对劲。claude-code-templates 这个名字看起来像某个仓库的主题实际上它代表了一类做法把 AI 编程工具需要知道的项目常识、反复使用的指令、质量检查规则沉淀成一套可复用、可共享的模板文件。这套东西解决的是个很现实的问题Claude Code 这类终端 AI 工具本身很强大但它的输出质量高度依赖上下文。项目背景、技术栈、目录约定、代码风格、已知陷阱这些信息你每次在对话里重新讲一遍既浪费时间又容易讲漏。模板的价值就是把这些“隐性前提”固化下来让 AI 每次开工前都自动加载。适合谁适合所有把 Claude Code 当日常生产力工具、但又不想每次从零调教它的开发者也适合想统一团队 AI 协作规范的团队负责人。1. 为什么说模板的地基是 CLAUDE.md模板可以做得花哨可以塞进去一堆命令和脚本但真正的地基只有一个CLAUDE.md。这个文件是 Claude Code 的项目记忆文件会话启动时会被自动读取相当于每次对话开始前 AI 都会“预习”一遍你写好的项目说明。地基不牢上面盖什么都是歪的。1.1 记忆文件的加载机制与层级Claude Code 读取记忆文件的规则是分层的。全局记忆放在用户目录下的~/.claude/CLAUDE.md项目级记忆放在项目根目录的CLAUDE.md还可以在子目录里放局部的 CLAUDE.md比如src/CLAUDE.md只描述前端部分的约定。加载时是叠加关系全局的常识加上项目的细节子目录的约束在 AI 进入对应区域时进一步生效。这个分层设计非常实用。我把所有项目通用的规则放在全局比如“代码里不允许出现 console.log 残留”“所有网络请求必须带超时和重试”“提交信息遵循 Conventional Commits”。这些是每个项目都适用的底线没必要在一个项目里写一遍换一个项目又写一遍。项目级的 CLAUDE.md 只写这个项目特有的东西技术栈、目录结构、启动命令、业务约束。一个常见的误解是 CLAUDE.md 越长越好恨不得把整个 README 和设计文档都塞进去。实际效果相反AI 的上下文窗口虽然大但信息密度过高时它对重点的把握反而会变差。我的经验是CLAUDE.md 应该控制在能让人在两分钟内读完的程度只留 AI 必须知道、且无法从代码里轻易推断出来的内容。1.2 能干活的项目记忆文件长什么样这里直接给一个我目前在用的项目级 CLAUDE.md 骨架你可以直接拿去改# 项目记忆库存管理服务 ## 一句话定位 面向中小商家的库存后端服务核心业务是商品、订单、库存流水。 ## 技术栈与命令 - 语言TypeScriptNode.js 20 - 框架Fastify - 包管理pnpm - 构建npm run build - 测试npm testVitest - 本地开发npm run dev ## 代码约定 - 所有业务错误必须抛出 BizError禁止裸 throw Error - Controller 只做参数解析和响应组装业务逻辑全部放 service 层 - 事务必须显式使用 withTransaction禁止跨 Service 隐式事务 - 文件名使用 kebab-case组件和页面文件除外 ## 已知陷阱 - /orders 查询带上 status 参数时必须走复合索引否则 DB CPU 会飙升 - 库存扣减必须带乐观锁条件在 SQL 里直接判 remaining quantity - 消息队列消费失败必须进死信队列不能静默吞掉 ## 当前模块地图 - src/modules/product商品模块含分类、SKU、价格 - src/modules/order订单模块依赖库存扣减 - src/modules/inventory库存模块核心是流水表注意几个细节技术栈部分必须带上可以执行的命令AI 需要知道怎么跑测试、怎么构建而不是只知道“这是 TypeScript 项目”。已知陷阱部分价值最高这些都是你自己踩过坑才写下来的AI 看到后会主动规避等于把你的经验迁移给了它。模块地图也很关键它让 AI 在接到任务时能快速定位代码位置而不是从根目录往下盲搜。1.3 给 AI 看的说明和给人看的文档是两回事CLAUDE.md 和 README 最本质的区别是README 写给人类看讲究背景介绍、功能展示、架构图CLAUDE.md 是写给 AI 的执行约束讲究的是可判定、可执行。什么叫可判定比如“代码要整洁”这句话就不可判定AI 不知道什么叫整洁。但你写“函数超过 80 行必须拆分”就可判定AI 可以参考执行。同样道理“注意性能”是空话但“查询订单列表必须走索引禁止全表扫描”是可执行的约束。写 CLAUDE.md 的时候每条内容都值得先用一个判断题过一遍如果给一个不了解这个项目的人他能根据这句话做出明确的行为改变吗如果能留下来如果不能删掉或者改写。保持这个标准你的 CLAUDE.md 才会越写越精炼而不是变成没人看的文档垃圾场。2. 让模板真正干活斜杠命令、Agent 与 hooksCLAUDE.md 解决的是“AI 知不知道项目背景”的问题但实际工作里还有另一类重复劳动你经常让它做的事。比如代码审查、重构前调整、生成测试、写提交信息。这些动作指令每次手打又长又容易漏斜杠命令、Agent 和 hooks 就是用来固化这些动作的。2.1 斜杠命令把一组动作打包成一个触发词Claude Code 支持自定义斜杠命令。你在对话里输入/review就能触发一段预设的指令流而不是每次都把“请检查安全、并发、可维护性重点看这几个模块……”这么长一段重新打一遍。命令文件是 Markdown 格式放在两个位置全局的~/.claude/commands/或者项目级的.claude/commands/。全局的适合所有项目通用的动作项目级的适合绑定某个项目的专属流程。一个命令文件的开头是 YAML frontmatter声明这个命令的描述、参数提示和允许使用的工具后面正文就是真正的指令内容。我拿最常用的代码审查命令举个例子--- description: 对指定文件做一次严格的代码审查 argument-hint: 文件或目录路径 allowed-tools: Read, Grep, Glob, Bash(ls, cat, git diff) --- 请对路径 {{argument}} 执行一次代码审查。 前置动作 1. 先找到该文件对应的测试文件 2. 用 git diff 查看最近改动的范围 逐项检查并输出结论 - 安全问题SQL 注入、越权、敏感信息泄露 - 并发与事务竞态条件、事务范围、锁粒度 - 错误处理是否存在裸 throw、是否吞掉异常 - 可维护性命名质量、重复代码、过长函数 输出格式 - 每个问题标注 [严重] 或 [建议] - 必须给出可落地的修改建议禁止泛泛而谈 - 最后汇总一个修复优先级列表这里有两个容易被忽略的细节。第一是allowed-tools字段它限制了 AI 在执行这个命令时能调用哪些工具。审查代码的时候我通常不允许它直接改文件只能读和查防止它“顺手”把代码改了。第二是输出格式的强制约束这让每次审查的结果都结构一致方便我快速扫读。模板好不好用往往就体现在这些约束的细致程度上。2.2 Agent把复杂任务拆给专职角色斜杠命令适合单线程的固定流程但真实项目里的任务往往是复合的比如“给订单模块加一个导出功能”。这种任务涉及数据层、服务层、接口层、前端展示如果一股脑塞给一个 AI 上下文去处理它很容易在不同模块之间来回横跳改完一个忘了另一个。我的做法是在模板里预设一套子代理角色。在命令文件中定义 Agent 的提示词让 AI 在处理复合任务时先以“架构师”角色梳理改动方案再以“后端实现者”角色写核心逻辑最后以“测试工程师”角色补测试。每个角色只关注自己的那部分约束产出的质量会明显更稳。实际操作上我会在命令正文中明确写出角色的切换顺序和边界。比如请按以下三个角色依次处理 1. 架构师分析本次改动涉及的文件和调用链输出改动方案 2. 实现者按方案实现代码严格遵守 CLAUDE.md 中的代码约定 3. 测试工程师为新增逻辑补充单测必须覆盖正常和异常分支子代理模式的本质是通过约束上下文范围来提升单点质量。让 AI 一次只干一类事比让它大包大揽要可靠得多这也是模板设计里最值得投入时间打磨的部分。2.3 hooks把质量检查做成自动化闸门hooks 是 Claude Code 的一个重要机制它在 AI 使用工具的前后或者一轮回复结束时触发预设的检查命令。这是我整套模板里投入产出比最高的一块。我现在的配置里有两个 hooks 效果非常明显。第一个是 PostToolUse 钩子匹配 Edit 和 Write 工具AI 每次改完文件后自动执行格式检查不符合规范的文件会被标记出来等于给 AI 的每次修改都过一遍 lint。第二个是 Stop 钩子AI 每轮回复结束时自动跑一遍相关的测试确保它没有把现有的测试改坏。hooks 的配置文件通常放在.claude/settings.json里示意配置大致长这样{ hooks: { PostToolUse: [ { matcher: Edit|MultiEdit, hooks: [ { type: command, command: npx prettier --check $(git diff --name-only -- *.ts *.tsx) } ] } ], Stop: [ { hooks: [ { type: command, command: npm test -- --changedSinceHEAD } ] } ] } }注意这里有个经验之谈hooks 的命令执行时间不能太长。如果每次 Stop 都跑全量测试大项目里一次要等几分钟AI 的响应速度会被拖垮。我后来改成了--changedSinceHEAD只测本次改动的部分耗时降到了一个可接受的范围。设计 hooks 时要时刻记住它是给 AI 增加摩擦的机制——有价值的摩擦是质量闸门没价值的摩擦是纯粹拖慢速度。3. 从零搭一套 claude-code-templates 的完整过程前面讲完了理论基础这部分是真正的实操。我会带你从零搭一套自己的模板仓库按步骤来每一步都可以直接落地。3.1 先盘点高频任务再做目录规划搭模板之前先别急着写文件。坐下来花十分钟回忆过去两周你在 Claude Code 里反复让它做的事列一个清单。我自己的清单是这样的代码审查每两天一次为新增功能补测试每天多次重构已有模块每周一到两次生成规范的 git 提交信息每天多次新项目初始化环境每月几次清单列出后再去掉那些你用现成工具就能解决的项剩下就是模板要覆盖的高频场景。拿上面的清单举例提交信息生成其实很多工具都能做可以不放模板里但代码审查和补测试的指令流程足够复杂非常值得固化成模板。目录规划上我建议采用一个独立仓库来管理模板结构如下claude-code-templates/ ├── CLAUDE.md # 模板库自身的说明 ├── commands/ │ ├── review.md # 代码审查 │ ├── test-gen.md # 测试生成 │ ├── refactor.md # 模块重构 │ └── init-project.md # 新项目脚手架初始化 ├── agents/ │ └── backend-impl.md # 后端实现角色 ├── hooks/ │ └── settings.example.json # hooks 示例配置 └── templates/ ├── webapp/ # Web 应用项目模板 ├── service/ # 后端服务项目模板 └── cli-tool/ # 命令行工具项目模板模板库和实际项目的模板要分开理解。templates/里放的是完整的新项目骨架包括基础的 CLAUDE.md、目录结构、配置文件/init-project命令负责把这些复制到新目录。commands/里放的是所有项目通用或项目可复用的斜杠命令。3.2 手写第一个斜杠命令并验证效果以测试生成命令为例写一个最用的test-gen.md--- description: 为指定模块或文件生成单元测试 argument-hint: 文件路径或模块名 allowed-tools: Read, Glob, Grep, Write, Bash(ls, cat) --- 为路径 {{argument}} 生成单元测试。 要求 1. 先读取目标文件梳理它导出了哪些函数 2. 读取对应的类型定义和依赖接口 3. 为每个公开函数编写测试用例 覆盖要求 - 正常输入的主路径 - 边界条件空值、极大值、重复值 - 异常分支抛错、超时、依赖返回错误 代码风格 - 使用 vitestdescribe/it 组织用例 - mock 外部依赖禁止发起真实网络请求 - 测试数据内联不依赖测试数据库 完成后运行 npm test -- 目标测试文件确认全部通过。写完命令文件怎么验证它是否真的可用我建议你开一个临时目录放一段真实的业务代码然后触发这个命令观察 AI 的行为是否符合预期。第一次触发大概率会有偏差比如测试结构不符合项目习惯或者 mock 方式不够优雅。这时不要急着改命令先把偏差记录下来然后修改命令文件的约束描述再触发一次。经过两三轮这样的迭代命令就会变得比较稳定。这个迭代过程是整个模板建设的核心工作流写命令、实测、发现偏差、改约束。没有这一步模板就只是纸面设计。3.3 内置模板的初始化和使用流程模板仓库里真正产生复利的是templates/目录下的项目骨架。每次新项目开工我执行/init-project选择一个模板类型然后回答几个问题比如项目名、包管理工具、目标框架。命令会自动完成复制骨架、替换变量、初始化 git、安装依赖这一整套动作。下面是一个 Web 应用模板的 CLAUDE.md 示例比前面那个更精简因为新项目还没踩过坑# 项目记忆 ## 技术栈 - React 18 TypeScript Vite - 路由React Router v6 - 样式Tailwind CSS - 测试Vitest Testing Library ## 命令 - npm run dev 启动开发 - npm run build 产物构建 - npm test 跑测试 - npm run lint 代码检查 ## 约定 - 组件文件使用 PascalCase其余文件名 kebab-case - 所有异步请求封装在 src/api 下禁止在组件里直接调 fetch - 错误提示统一使用 toast禁止 alert实际使用时你会发现初始化模板只是一个起点。项目真正开始沉淀经验是在你往 CLAUDE.md 里一条条添加“已知陷阱”之后。模板库提供的是基线真正让它变得有价值的是每个项目在推进过程中的持续更新。4. 实测效果对比有模板和没模板的差距讲了这么多设计思路最后还是得用数据说话。我把自己在真实项目里使用模板前后的对比整理了一下包含场景、行为和结果三个维度。4.1 代码审查场景的差距没有模板的时候我让 AI 审查代码它通常给出类似“代码整体质量不错但有一些地方可以优化”的评价然后挑几个无关痛痒的小问题。这不是敷衍而是因为 AI 没有明确的检查标准它只能凭通用经验来判断。有模板之后审查命令明确要求逐项检查安全、并发、事务、错误处理每个问题要标注严重级别并给出具体修改建议。实际出来的结果是AI 开始关注到 SQL 注入面、竞态条件、事务边界这类真正要命的问题。曾经在一次订单模块的审查中它发现了一个库存扣减不带锁的并发隐患这个问题我在 code review 里肉眼看了两遍都没看出来。代码审查从“经验分享”变成了“结构化检查”这是模板带来的最大变化。AI 的输出质量并不取决于模型本身聪不聪明更多取决于你给它的检查清单细不细。4.2 重构与测试生成场景的对比重构场景下没有模板时 AI 容易“自由发挥”改完业务代码忘了同步更新测试或者改坏了现有的测试用例。我的重构命令里专门加了一条硬约束“重构完成后必须运行完整测试套件并汇报失败用例失败时必须修复到全部通过”。加了这条约束之后重构任务的一次通过率明显提升。测试生成是模板收益最直接的场景。没有命令约束时AI 生成的测试经常出现“为了覆盖率而测试”的情况全都是断言函数返回值不为空这种没有意义的用例。命令模板对覆盖分支做了强制要求后测试的质量提升了一个档次开始出现边界条件测试和异常路径测试这些都是人工补测试时最容易漏的部分。下面这个表格是我个人项目中的一个简单统计场景无模板行为有模板行为主观效率变化代码审查泛泛而谈的输出结构化检查给出问题级别和修改建议约提升 1 倍测试生成主路径覆盖缺少边界主路径加边界加异常覆盖约提升 2 倍重构带错测试强制重构后跑全套测试返工明显减少新项目初始化每次手动解释技术栈复制模板改参数即可开工节省半天表格里的数字是我自己的体感估值不同项目会有差异但方向上是一致的模板对重复性任务的效率提升最明显对创造性任务的帮助相对有限。4.3 模板真正值钱的地方在于“稳定”而不是“惊艳”有一个反直觉的体会是模板带来的最大价值不是让 AI 偶尔爆发出惊艳表现而是让它的稳定输出水平被托底了。没有模板的时候AI 的输出像过山车——状态好的时候它自己就能理清思路状态差的时候它会做出完全不合项目习惯的设计。有了模板之后下限被抬高了。CLAUDE.md 里的约定它每次都会加载斜杠命令里的约束它每次都会执行hooks 还会在它跑偏时把它拉回来。哪怕我不附加任何额外的解释它的产出也能保持在项目约定的标准线上。对团队协作来说这种稳定性比偶尔的惊艳重要得多。因为可预期的产出才能成为协作流程的一部分。5. 踩过的坑和模板的团队共享建议模板的收益不是白来的。我在这套东西上踩了不少坑有些至今还在影响我维护模板的方式写出来给你做个参考。5.1 把 CLAUDE.md 写成教程是最常见的错误第一个坑是 CLAUDE.md 越写越像教程。有段时间我在里面加入了大段的背景说明“本项目采用领域驱动设计核心思想是……”这类文字。结果 AI 变得“话痨”起来回答问题时总要先复述一遍设计理念真正干活的效率反而下降了。后来我把所有描述性、解释性的文字全部删掉只保留可执行约束。那句“采用领域驱动设计”改成“聚合根的领域逻辑必须封装在 domain 层禁止在 application 层直接操作实体”——同一个意思但后者是可判定的约束。这个改动之后AI 的输出明显干净了。检查模板内容时我给自己定了一个简单标准每一行都必须是一个可以执行“是或否”判断的规则。不能满足这个标准的一律从模板里移除。5.2 命令文件过度膨胀导致的执行偏差第二个坑是斜杠命令越写越长。早期我担心 AI 理解不到位把命令写成了一篇小作文从背景介绍、前置条件、检查清单到输出模板全都塞进去。结果是 AI 在执行时抓不住重点总是纠结于细枝末节的格式要求核心的审查逻辑反而执行不到位。后来我把命令的背景描述全部删掉只留下动作指令、约束条件和输出格式命令文件精简到几十行以内。AI 的执行准确率反而上来了。这个经验让我意识到模板文件的每一行都必须有明确的作用任何“补充说明”性质的内容都是噪音。如果有些背景确实重要应该写进 CLAUDE.md 而不是命令里。5.3 团队共享时的版本管理与分工最后聊聊多人协作场景。如果只是个人使用模板放在自己的~/claude/目录下就够了。但团队要共享模板我就建议用独立仓库管理并且走正规的代码评审流程。我自己维护的团队模板库改任何一个命令都要开 PR由至少一人 review 后合入跟管理业务代码一样严肃。模板库的变更管理有个好处因为改动经过了评审模板的演化方向是被控制住的不会出现“某个人拍脑袋加了一条全局约定结果所有人项目里的 AI 表现都变了”的失控局面。全局命令的修改尤其要谨慎它影响的是所有成员的项目。另外建议在模板仓库的根目录留一份 CHANGELOG记录每次改动的原因和影响范围。我在实际维护中发现模板的改动常常会在双方配合上产生“我没有这个命令”“我这边 hooks 版本对不上”等沟通问题。有一份清晰的变更历史就能快速定位是谁的模板库版本落后了。如果你刚开始搭自己的 claude-code-templates我的建议很简单不要一上来就想做一套覆盖所有场景的“宇宙级模板”。先把 CLAUDE.md 写好再挑一个你天天用的高频场景写一个命令加上一个能守住质量底线的 hook这就已经超过大多数人了。先用起来再根据真实的 AI 响应反馈去迭代模板会在迭代过程中自然长成你需要的样子。我现在每接手一个新项目第一件事不是写业务代码而是花半小时把 CLAUDE.md 和两个最常用的命令先立起来这个习惯帮我省下的时间远超过当时搭建模板投入的时间。
阅读完成 · 觉得有帮助？
