过去大半年我把 Claude Code 从一个偶尔尝鲜的命令行工具用成了日常开发里离不开的搭档。真正让我从“每个新项目都得重新花半小时教它这项目是干嘛的”里解脱出来的是一套我不断迭代的 claude-code-templates。它不复杂核心就三样把项目说明书整理成可复用的 CLAUDE.md 模板把高频操作固化成斜杠命令模板再用 hooks 把没有商量余地的检查自动化。如果你也在用 Claude Code 写代码、跑数据分析、维护文档而且不想每次开新会话都从零解释项目背景那么这篇内容基本可以当作一份可直接照搬的模板库使用说明书。1. 为什么 Claude Code 需要一套模板从“每次重新调教”到“一次沉淀反复用”1.1 裸奔的 Claude Code 是什么样的第一次从终端敲下claude进入一个空仓库时它就像一个很有天分但完全不认识这个项目的新同事。你告诉它这是 React 项目它写出来的组件确实像模像样但一旦涉及私有组件库、内部构建方式、特殊数据流它就频繁犯错。原因也简单没有 CLAUDE.md 或类似的说明文件时它对项目的认识完全来自你当前会话里说了什么以及它自己扫目录得到的一知半解。对于小仓库可能够用对稍微有点历史的项目你会发现自己一直在做“翻译”工作把本应写进文档的知识一遍遍敲给 AI 听。这个状态我称之为裸奔。裸奔最浪费的还不是你的打字时间而是会话上下文。每句话都在解释背景解释本身占据记忆空间真正用于推理的有效信息被稀释。遇到代码量大的仓库它还会翻出一些无关模块作为依据一本正经给出错误改法。我不止一次看到它为了完成一个表单需求把另一个模块里完全不相关的工具函数拉进来最后改出一堆没人想维护的代码。从根上解决这个问题就是给它一份准确、够用的项目说明书让它在开口之前先知道自己在哪。1.2 模板到底沉淀了什么模板不只是一段提示词它是在沉淀三类东西。第一是事实项目是做什么的、技术栈是什么、目录怎么组织、入口在哪个文件。第二是规则代码风格、命名习惯、提交信息格式、什么能改什么不能改。第三是流程完成一个需求的步骤、跑测试的方式、发布前必须做哪些检查。事实让 AI 答对问题规则让它做得符合预期流程让它按正确顺序干活。我常用的比喻是把模板当成给代班同事留的交接文档。你不在的时候模板就是唯一能约束它的东西。你希望它按你的方式处理问题就得把方式写下来。一份好的 CLAUDE.md 模板本质上就是在替未来的你说清楚那些“我以为它应该知道但它其实完全不知道”的东西。定期维护模板等于把你和 AI 协作过程中踩过的坑都转化成了下一次协作的起点。1.3 什么项目最适合用模板先泼一点冷水模板不是万能。一次性脚本、纯探索性的 notebook、三五天就删的 demo不值得为它们维护模板。但下面几类项目非常值得一是会持续迭代的 Web 应用或 API 服务二是团队协作项目三是仓库本身有一定复杂度、新人进来需要时间上手的项目四是重复性很高的工具型仓库比如你经常从零搭一个类似脚手架。判断标准就一条你在这个项目上和 AI 的协作次数是否超过二十次如果超过模板一定划算因为后续每次会话都在为第一次写文档的时间买单。2. 模板库的整体布局目录、命名规范与分层思想2.1 我采用的目录结构整个模板库我用一个 git 仓库管理结构如下claude-code-templates/ ├── README.md ├── project/ │ ├── web-app/ │ │ ├── CLAUDE.md │ │ ├── README.md │ │ ├── commands/ │ │ │ ├── test.md │ │ │ ├── build.md │ │ │ ├── review.md │ │ │ └── fix.md │ │ └── hooks/ │ │ ├── settings.example.json │ │ └── scripts/ │ ├── cli-tool/ │ ├──># 项目名称 一句话说明这个项目做什么、给谁用。 ## 技术栈与结构 - 语言/框架/运行时TypeScript、React、Vite - 关键目录src/renderer 放前端src/main 放 Electron 主进程 - 入口文件src/main/index.ts ## 常用命令 | 场景 | 命令 | | ---- | ---- | | 安装依赖 | pnpm install | | 启动开发 | pnpm dev | | 运行测试 | pnpm test | | 构建 | pnpm build | ## 编码约定 - 组件用函数组件 hooks不用 class 组件 - 后端接口封装在 src/api 下禁止在组件里直接 fetch - 错误处理统一返回 { code, message }不要抛裸字符串 ## 工作流约定 - 功能开发先写测试再补实现 - 提交信息使用 conventional commits - 发布前必须跑全量测试和 lint ## 项目红线 - 不要把敏感信息写进日志 - 不要修改 src/generated 下的生成文件 - 数据库迁移必须新增迁移文件而不是修改旧文件项目红线段落是 AI 最容易受益的部分。诸如“不要把密码打日志”“自动生成的代码别手改”这类信息对人是常识对 AI 则完全是盲区。不写清楚它迟早踩一次写清楚之后它在做相关操作时会主动停下来。3.2 自定义命令模板让高频操作变成“一个斜杠”CLAUDE.md 解决“懂项目”斜杠命令解决“听指挥”。我会把项目里所有高频操作写成命令模板。以test.md为例frontmatter 的description字段会在斜杠命令列表里显示正文则是给 Claude 的指令--- description: 运行全量测试并修复失败用例 --- 运行 pnpm test。如果失败先阅读失败输出区分是逻辑问题还是测试本身的问题。 修复后再次运行直到全部通过。不要修改现有测试的断言除非你确认断言与需求不符。 修复过程中保留所有测试文件的修改记录最后用一句话总结每个失败用例的根因。命令模板看起来只是几行字价值在于确定性。每次手动输入“跑一下测试如果失败就看看是不是断言写错了”语气和重点都可能不同而模板能保证每次执行的检查标准完全一致。团队协作时这份一致性尤其值钱因为不同人口中的“跑测试”可能差很多有人只想跑单测有人要 lint 加单测再加类型检查。3.3 hooks 钩子模板把“必须做”变成“自动做”hooks 是在工具调用前后自动执行脚本的能力适合强制类的检查。我的模板里有三个固定钩子PostToolUse捕获测试命令的输出摘要避免一长串日志占满上下文PreToolUse在执行 Edit 前做文件路径保护Stop之前检查是不是有未完成事项。下面是一个简化的结构示意{ hooks: { PostToolUse: [ { matcher: Bash(pnpm test|pytest|go test), hooks: [ { type: command, command: node .claude/hooks/scripts/collect-test-summary.js } ] } ], PreToolUse: [ { matcher: Edit, hooks: [ { type: command, command: node .claude/hooks/scripts/check-protected-files.js } ] } ] } }不同版本的配置字段可能会有差异使用前以官方文档为准。hooks 的审美能不用就不用用就用在“违反规则会造成明显代价”的场景。不要在每次文件编辑后都调用重量级检查也不要让钩子脚本阻塞太久。模板里放钩子脚本时必须考虑脚本本身的幂等性重复执行不应该产生重复副作用。3.4 技能模板把完整方法论装进去如果你用 Claude Code 的时间比较久会发现有些知识不是项目规则而是一套完整流程。例如“代码审查”先读 diff、再逐个文件 check、输出带严重级别的问题列表。这种场景用 skills 管理比塞进 CLAUDE.md 更合理因为 skills 需要时才会被加载不会每轮会话都消耗 context。我给模板库默认配了review、refactor、debug三个基础技能名称固定内容随项目微调。--- name: code-review description: 对未提交的改动进行代码审查输出严重级别的问题列表 --- ## 触发场景 在提交前、创建 PR 前或怀疑某次改动有隐患时。 ## 审查步骤 1. 获取当前分支相对目标分支的 diff。 2. 按文件逐个检查重点关注逻辑正确性、边界条件、错误处理、安全性。 3. 输出问题清单每条标注严重级别blocker / major / minor / nit。 ## 注意事项 - 只报告确有问题的地方不为了凑数量提建议。 - 对不确定的问题标注“需确认”不要断言。我的经验是CLAUDE.md 放“是什么和为什么”skills 放“怎么做”。把进入某个项目需要知道的背景放记忆把跨项目通用的能力放技能这样新项目复制模板时技能文件几乎不用改只改 CLAUDE.md 就好。4. 实测一个从模板启动的新项目完整流程与效果对比4.1 从模板启动一个新项目的完整步骤拿最小 Web 工具举例做一个短链接管理页。第一步复制project/web-app模板到新目录第二步全局替换关键词把{{PROJECT_NAME}}换成实际项目名把模板里假命令换成真实命令第三步改 CLAUDE.md 的技术栈描述去掉不涉及的段落第四步启动claude直接提需求。之后的会话里我不需要再解释项目背景。模板里我特意用{{PROJECT_NAME}}这种全大写标识初始化时用编辑器全局替换一眼就能扫到有没有漏改。初始化步骤也写在模板的 README 里防止复制后出现漏改。整套初始化时间控制在十分钟内其中大部分时间花在确认技术栈细节上。4.2 和不用模板的对照差异在哪里对比项不用模板用模板首次会话“懂项目”时间5-10 分钟连续解释1 分钟内直接干活命令记忆每次都要重新告诉它从 CLAUDE.md 自动读取编码风格一致性取决于你当时的提示词规则固定可 review自动化检查靠人肉提醒hooks 自动卡点新成员接入成本每个人都要重新踩一遍克隆模板即可最直观的变化是“废话变少了”。不用模板时我经常要在需求描述后补一句“记得先看现有代码结构再动手”因为光说要加个功能它可能真的会在根目录新建一个文件而不是放进约定目录。用了模板之后这些问题大部分消失因为目录结构已经写在 CLAUDE.md 里。不仅是效率提升更重要的是会话里的有效上下文更多生成质量也随之提高。4.3 实测中的三个坑第一个坑是复制模板后忘记替换项目名。Claude 满嘴上一个项目的术语一度让我怀疑模板坏了。教训是初始化时先跑一遍全局搜索{{确认没有遗留占位符。第二个坑是命令模板里写死 npm但项目实际用 pnpm。每次/test都执行npm test输出里全是Missing script浪费了好几轮对话才发现。教训是命令模板里的包管理器不要写死要么用参数要么在 README 的初始化步骤里明确标注要先改这一行。第三个坑是 hooks 脚本没有加运行锁。那个脚本本来是在测试结束后把结果摘要追加到一个临时文件结果PostToolUse触发了一次脚本内部某个逻辑又调用了测试命令形成二次触发摘要被追加两遍。加了一个简单的状态标志之后才稳定。教训是凡是可能重入的钩子脚本都必须处理幂等。5. 模板的常见坑与迭代维护方法5.1 限制模板体积上下文预算要精打细算模板的本质是上下文预算分配。CLAUDE.md 每多一百个字就会在每次会话里占用一百个 token。所以我会给模板立规矩CLAUDE.md 不超过 500 行超过的部分必须拆到按需读取的文档。模板库本身也一样不要把所有历史项目的经验都堆在一个文件里否则每个项目都会带着一堆无关规则运行。判断标准是这条规则是否适用于此项目的每一次会话如果只在某些场景才需要就不应该常驻而应该放 docs 或 skill 里。例如“发布流程”很长就只在 CLAUDE.md 里保留一行“发布遵循 docs/release.md 中的流程”等真正要做发布时Claude 再自行读取。5.2 处理多份模板冲突给 AI 一个明确裁决依据项目级、团队级、个人级模板叠加时冲突无法避免。我建议在项目级 CLAUDE.md 里写一行固定话术“若本文件与团队或个人级别说明冲突以本文件为准。”反过来团队模板可以声明强制底线比如安全相关的规则不能由项目级覆盖。关键是让 AI 有明确的冲突裁决依据而不是让它凭感觉猜。我有一个实际教训团队模板要求所有函数写 JSDoc某项目模板没写这条导致 AI 在团队成员看来风格不一致。后来在项目模板里加了一句“团队模板中的注释规范适用于本项目”问题立刻消失。模板冲突不会消失但裁决规则可以提前写好。5.3 钩子脚本稳定性别让自动化变成中断源钩子脚本在无人值守时触发最容易翻车。所有脚本要写日志要捕获异常失败时不要阻塞主流程至少输出可以追问的错误信息。我加了一个约定任何 hooks 脚本执行超过十秒都算异常模板里禁止出现长时间运行的钩子。像 lint 这种重操作不要放在每次 Edit 后而是放在测试命令触发后。另一个稳定性的点脚本里的路径必须用绝对路径或基于项目根目录解析不能假设当前工作目录。很多钩子出问题就是因为 Claude 在子目录执行命令时脚本用相对路径找文件找错了地方。5.4 让模板持续演进把每次会话变成一次回顾模板不是写完就完。我会在每次会话结束前留意 Claude 是否问了一个“它本应该知道”的问题这通常意味着模板缺了一段内容。出现两次就把答案沉淀进模板。例如有一次它连续两个会话都在问“这个项目的 mock 数据放哪”我就在 CLAUDE.md 里加了一行目录说明。模板库用 git 管理提交信息写明变更原因。例如“新增 pnpm 场景的命令模板修复写死 npm 的问题”。这样半年后回看你能知道每个设计当时为了解决什么问题。模板库如果只是往里面堆内容会越来越臃肿但如果你把每次新增都当成一次有记录的决策它就会变成一件越用越顺手的工具。最后再分享一个小技巧在 CLAUDE.md 里留一个“当前项目状态”区块每次开始重要会话时让 Claude 先读取并更新它。长期项目有了状态位“上次进行到哪里”就不再依赖聊天记录也避免换新会话后从头开始。这个习惯我保留了大半年也是 claude-code-templates 里我最舍不得去掉的一部分。