过去大半年，我把 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 里我最舍不得去掉的一部分。
