小半年时间里，我用 Claude Code 反复建的项目加起来大概有二十多个。刚开始每开一个新项目，都是从一个空白目录开始：先手写一段大而全的系统提示，把技术栈、编码习惯、禁止事项一股脑丢进去，然后祈祷它在后面几周里不会跑偏。结果自然是时好时坏——同一个模型，换一个项目、换一个会话，发挥水平就像开盲盒。
后来我专门花了一周时间整理 claude-code-templates 这套工作流模板，把所有重复的配置、提示、命令和规则全部固化下来。效果立竿见影：新项目从"重新教育模型"变成了"直接应用已有规范"，团队同事接手时也不用再从零摸索。这篇文章会把整个整理过程、模板骨架、命令设计思路和踩过的坑都摊开讲，希望能给你一个可以直接抄作业的起点。
1. 先搞清楚模板到底在解决什么问题
很多人第一次接触 Claude Code 模板，会下意识认为它就是一堆提示词模板，无非是把系统提示写得更长一点。这个理解差得很远。
1.1 真正的问题是"每次都重新解释"
我观察到的普遍现象是：大多数人用 Claude Code 的前三天效率极高，之后开始断崖式下降。原因不是模型变笨了，而是上下文里那些约定俗成的信息在不断丢失。
举个例子，你做一个 TypeScript 项目，定了三条规矩：组件用函数式写法、测试文件必须放在__tests__目录下、错误处理统一用 Result 模式。第一天你花了几句话把这些写进对话，模型执行得很好。第二天新开会话，模型不记得这些了，你又得重新说一遍。到了第三个项目，你发现同样的话已经重复了十几遍，每次还都说得不太一样。
模板要解决的核心问题就是这件事：把散落在对话里、脑子和 PR 评论中的隐性知识，沉淀成项目目录里的一份显性文件。Claude Code 启动时会自动读取项目根目录下的CLAUDE.md，把它当作默认的项目背景信息。这意味着只要模板到位，新会话第一次开口就已经"知道"全部规矩，不需要人类重新教一遍。
1.2 模板经济的三个层次
从价值角度，我习惯把模板分成三个层次：
| 层次 | 内容 | 解决什么问题 | 投入产出比 |
|---|---|---|---|
| 第一层 | CLAUDE.md项目记忆文件 | 代码规范、架构说明、常用命令 | 中，但要持续维护 |
| 第二层 | .claude/目录工程化配置 | 权限、命令、钩子、子代理 | 最高，一次配置长期受益 |
| 第三层 | 整仓模板骨架 | 新项目初始化、团队标准化 | 高，适合多人协作 |
只做第一层的人占大多数，这也是为什么很多人觉得"模板也就那样"。真正让模板值钱的，是第二层和第三层的工程化组合。后面几个章节我会把这几个层次逐一拆开。
1.3 你该不该现在就做模板
当然，也不是所有人都需要建一套完整的模板体系。我的判断标准很简单：
- 如果你只是拿 Claude Code 做些一次性脚本、临时探索，模板纯属过度设计，手写几句提示就够了。
- 如果你在一个代码库上长期迭代，至少需要一份
CLAUDE.md。 - 如果你的团队有多个人用同一个代码库，或者你会频繁开新项目，那模板体系就值得认真搭。
最难的不是搭模板，而是持续维护。很多人的模板建完两周就过期了，最后变成一坨没人愿意碰的死文件。这一点我在最后一节会展开讲。
2. 模板的根基：一张高质量的 CLAUDE.md
无论模板体系做得多复杂，根基永远是CLAUDE.md。它被 Claude Code 自动加载，是你和模型之间最稳定的"共同记忆"。
2.1 CLAUDE.md 在上下文里的位置
先说清楚它的读取机制，这决定了你该怎么写。
Claude Code 加载记忆文件的顺序大致是：系统内置提示 → 用户全局配置（~/.claude/CLAUDE.md）→ 项目根目录CLAUDE.md→ 子目录里的CLAUDE.md。加载顺序意味着越靠后的文件，在具体场景下优先级越高，但同时也离"用户明确指示"越远。
这意味着两件事：第一，全局配置只写所有项目通用的偏好，比如"回答用中文"、"每次改动前先列执行计划"这类个人习惯，千万别写某个项目的专属内容。第二，项目级CLAUDE.md是每个项目的主战场，要覆盖的是这个仓库特有的信息。
2.2 一份结构合理的 CLAUDE.md 骨架
我花了很多版本迭代，最后收敛成下面这个结构。你可以直接拿来当模板：
# 项目概述 - 项目定位：一句话说清楚这是什么，给谁用 - 技术栈清单：语言、框架、关键库及版本 - 目录结构速览：src、tests、scripts それぞれ干什么 # 常用命令 - 启动开发环境：npm run dev - 运行测试：npm test - 代码检查：npm run lint - 构建产物：npm run build - 注意：命令必须从项目根目录执行，遇到子目录请先 cd 回根目录 # 代码规范 - 语言/框架约定：TypeScript 严格模式、函数式组件、命名规则 - 目录约定：组件放 src/components，页面放 src/pages - 错误处理：统一使用 Result 模式，禁止直接 throw 裸对象 - 样式方案：Tailwind + CSS Modules 分层使用 # 架构注意事项 - 数据流向：展示层 → 业务层 → 基础设施层，禁止反向依赖 - 状态管理：全局状态只放跨页面共享数据，局部状态用组件内 state - 接口规范：所有后端调用统一走 api/ 目录下的封装 # 工作流规则 - 修改文件前先说明改动的文件和原因 - 涉及数据库结构变更时，先询问再动手 - 提交代码前必须跑一遍 lint 和对应模块的测试 - 不确定的需求点直接提问，不要自行假设 # 禁止事项 - 不要修改 auto-generated 目录下的文件 - 不要使用 console.log 做调试输出，统一用 logger - 不要在业务代码里写死环境相关的配置这个结构的关键在于"只写模型不知道的事"。技术栈是 React 这种常识可以不写，但"这个项目的目录约定"、"数据流的强制方向"、"提交前必须跑哪些命令"这类只有在这个仓库里才成立的信息，一定要写清楚。
2.3 别把 CLAUDE.md 写成百科全书
我见过最离谱的项目CLAUDE.md有九百多行，事无巨细，连缩进用几个空格都写了。模型不是每句话都会百分百执行，文件太长时注意力会被稀释，反而最关键的规则被忽略了。
经验准则是：一个文件，重点规则控制在二十条以内，只保留"违反就会出大问题"的内容。次要内容拆到.claude/commands里的命令模板或者子代理的系统提示里，需要时再调出来，而不是一股脑塞进主记忆文件。另外，CLAUDE.md写多了之后一定要自己通读一遍，很多看似明确的规则，站在模型的角度其实是自相矛盾的。
3. 比 CLAUDE.md 更值钱的：.claude 目录里的工程化配置
CLAUDE.md只是解决了"模型知道规矩"的问题，而.claude/目录解决的是"模型能按规矩行动"的问题。这才是模板体系里最容易被低估的部分。
3.1 settings.json：把权限与行为固化下来
项目级配置文件是.claude/settings.json，它控制 Claude Code 在这个项目里的权限范围和自动化行为。一个典型的配置是这样：
{ "permissions": { "allow": [ "Bash(npm test)", "Bash(npm run lint)", "Bash(npm run build)", "Read(**)" ], "deny": [ "Bash(git push --force)", "Bash(rm -rf *)" ] }, "hooks": { "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npx prettier --check CHANGED_FILES" } ] } ] }, "model": "按团队统一选用的模型版本填写" }权限配置的意义是双向的。对模型来说，明确的 allow 列表意味着它可以放手执行测试、构建这些高频操作，不需要每次弹窗向你确认；对团队来说，deny 列表是底线，防止模型顺手执行危险命令。
3.2 hooks：让模型的行为可校验
hooks 是模板里自动化程度最高的部分。Claude Code 会在特定事件触发时执行你配置的命令，让每次改动都被校验。
最实用的两个场景：
PostToolUse配合Edit匹配器：模型每改完一个文件，自动跑一遍代码格式化检查或 lint，把问题当场暴露。PreToolUse配合Bash匹配器：在模型准备执行敏感命令前做一次拦截。
写 hooks 时有个关键点容易被忽略：hook 脚本本身要稳、要快。如果你的格式化工具需要两三秒才能跑完，模型每改一个文件都要等这么久，整体效率会非常糟糕。所以我会把耗时长的检查放在Stop事件里做汇总报告，而不是放在每个Edit之后。
3.3 settings 的作用域划分
Claude Code 的配置有多个层级，我强烈建议按这套规则来划分：
~/.claude/settings.json：个人全局偏好，比如通用权限、个人风格的输出格式。.claude/settings.json：项目级配置，提交到仓库，团队共享。.claude/settings.local.json：个人针对本项目覆盖的配置，不提交仓库，比如你本地测试用的特殊环境变量。
把这三者分开，是模板可以跨人复用的前提。很多团队模板"推不下去"就是因为在项目级配置里混入了某个人的个人习惯，其他人一上来全是弹窗和冲突。
4. 把高频动作固化成命令模板
如果说CLAUDE.md是知识，commands 就是"动作的快捷键"。这一步做完，模板的使用体验会有质的飞跃。
4.1 什么是命令模板
在.claude/commands/目录下，每个 Markdown 文件对应一个斜杠命令。比如.claude/commands/review.md对应/review。
一个命令模板包含两部分：文件开头的 YAML 元信息和正文的指令：
--- description: 对当前改动做一次结构化 Code Review argument-hint: [可选] 指定文件或模块 allowed-tools: Read, Grep, Glob model: 与项目主模型一致或使用更强推理模型 --- 你是一位严格的资深代码评审者。请对本次改动的代码进行结构化审查，重点检查： 1. 逻辑正确性：是否存在边界条件遗漏、并发问题或明显的逻辑错误 2. 安全性：是否引入了注入、越权、敏感信息泄露等风险 3. 可维护性：命名、函数长度、模块职责是否合理 4. 与项目规范的符合度：对照 CLAUDE.md 里的代码规范逐条核对 输出格式： - 问题列表（按严重程度排序，标注所在文件和行号） - 每个问题给出修复建议，并注明是否必须修改 - 最后给一个总体结论：通过 / 有条件通过 / 不通过元信息里的description是给模型理解命令用途的，allowed-tools限定了这条命令能调用哪些工具，argument-hint提示用户跟在该命令后面的是什么参数。
4.2 我沉淀下来的一套高频命令集
用几个月下来，我的模板仓库里常驻这几条命令，几乎适配所有项目：
| 命令 | 触发场景 | 解决的核心痛点 |
|---|---|---|
/review | 提 PR 前或改动完成后 | 让模型以评审者身份重新审视代码，而不是顺着写作思路自夸 |
/fix-lint | 收到 lint 错误时 | 统一修复格式问题，不改变业务逻辑 |
/test-case | 加新功能时 | 根据函数签名自动补测试用例，覆盖边界条件 |
/commit | 准备提交代码时 | 生成规范且符合团队 Commit Message 格式的提交信息 |
/explain | 接手不熟悉的模块 | 按调用链由外向内拆解模块职责，输出架构笔记 |
这里特别说一下/review的设计思路。很多人让模型做代码审查，结果是模型把自己的思路又夸了一遍。原因很简单：写代码和审代码是同一个会话，模型天然倾向于维护自己之前的产出。把审查单独做成一条命令，等于明确切断了"作者视角"，让模型切换成独立的评审者角色，效果完全两样。
4.3 命令模板与 CLAUDE.md 的分工
命令模板和CLAUDE.md的边界在哪里，我一开始也处理得很乱。后来总结出一句话：CLAUDE.md写被动规则，commands 写主动任务。
CLAUDE.md里的规则是每时每刻都生效的约束，比如"不要改自动生成的文件"；而命令模板是用户主动发起的工作流，比如"帮我审查这次改动"。如果一条复杂的流程被写进CLAUDE.md，模型反而因为指令太长而失去重点；把流程放在命令里，只有你主动召唤时它才需要理解和执行。
5. 搭一个能沉淀、能传给团队的模板仓库
当你把单项目的模板玩顺之后，下一步的自然需求是：能不能把它抽成一套可复用、可分发的东西？我的做法是维护一个独立的模板仓库，所有公共资产都放在里面。
5.1 仓库结构与设计原则
我的claude-code-templates仓库结构大致是：
claude-code-templates/ ├── README.md ├── templates/ │ ├── nextjs-ts/ │ │ ├── CLAUDE.md │ │ ├── .claude/ │ │ │ ├── settings.json │ │ │ ├── commands/ │ │ │ │ ├── review.md │ │ │ │ ├── commit.md │ │ │ │ └── test-case.md │ │ │ └── agents/ │ │ └── .gitignore │ ├── python-api/ │ └── go-service/ ├── scripts/ │ ├── apply.sh │ └── init.py └── CHANGELOG.md设计上我坚持三条原则。
第一条，按技术栈分模板，而不是按项目分模板。同一个技术栈的项目，约定往往高度相似，合并维护成本最低；每个具体项目的业务差异通过项目里的CLAUDE.md补充。
第二条，每个模板目录自包含。一份CLAUDE.md、一套.claude配置配套齐全，可以直接复制到任何空目录里用。不要让使用者在多个目录之间手动拼装，拼装过程一定会出错。
第三条，模板仓库必须有一个 CHANGELOG。模板和普通代码一样会演化，改了哪个通用规则、为什么改，都要留痕。否则三个月后没人知道之前为什么那样定，也不敢动它。
5.2 落地到新项目的两种方式
把模板应用到新项目，两种方式我都用过。
第一种是最朴素的复制粘贴，手动把模板目录里的文件拷过去。优点是零依赖，缺点是容易漏文件。
第二种是写一个初始化脚本。比如scripts/apply.sh接收一个模板名和目标目录参数，自动把对应目录下的文件复制过去，并替换模板里的占位符（例如项目名、模块名）。GitHub 上的模板仓库大多用这种方式。我用 Python 写了个init.py，还加了一个交互式问答：问用户项目名、包管理器偏好、是否需要 ESLint 严格模式等，然后把回答写进生成的CLAUDE.md。
脚本化的价值不只是方便，更重要的是它强制模板在"可用状态"下被维护。复制粘贴时你可能会容忍某些过期的片段，但脚本一旦跑不通，你当天就得修。
5.3 团队推广中最容易忽略的一件事
模板推给团队，技术难度从来不是瓶颈，瓶颈在于"每个人的使用习惯不同"。有人喜欢让模型多问问题，有人喜欢它闷头干活；有人用 default 模型，有人切了更强的推理模型。
所以我的建议是：模板仓库里只放团队共识部分，个人偏好部分一律用settings.local.json覆盖。同时，在 README 里明确写清楚"哪些文件必须用模板的、哪些可以本地覆盖"，把改模板的流程变成一次正式的 code review 而不是谁想改就改。
6. 折腾大半年后，踩过的坑和想明白的事
最后这部分写我最想分享的几段真实教训。模板这件事，光看理论永远觉得简单，踩过坑才知道边界在哪里。
6.1 CLAUDE.md 越长，模型越记不住
这是我最开始犯的错。总担心模型不了解项目背景，于是什么细节都往CLAUDE.md里塞，最长的一个版本写了三百多行。结果实测发现，模型在执行到一半时经常把早期写在CLAUDE.md里的规则忘掉，我不得不反复提醒。
后来我把文件压到一百行以内，并用"负面清单"的方式写规则——不写"应该怎么做"，只写"禁止怎么做"。实测效果反而好很多，模型对否定式约束的遵守率明显更高。
6.2 hook 脚本失败不等于流程失败
我踩过最隐蔽的坑是 hooks 的静默失败。有一版模板里我在PostToolUse中挂了一个 ESLint 检查脚本，但脚本依赖的 Node 版本在某个同事机器上不对，hook 抛错了。诡异的是，Claude Code 并不会因此中断整个流程，错误只在日志里出现一行，不主动看根本发现不了。
从那之后我给自己立了一条规矩：hook 脚本必须内部兜底，命令本身要写|| true之类的容错，同时把失败信息输出到固定的日志文件。脚本的正确性要单独测试，不能依赖模型每次帮你发现问题。
6.3 模型"知道但不遵守"≠模板写得不对
还有一种经常让人沮丧的情况：CLAUDE.md里明明写了"提交前必须跑测试"，模型还是偶尔跳过。我一度以为是模板不行，反复调整措辞。后来才想明白，模板负责的是把信息传达给模型，但模型的实时决策还会被上下文中的其他因素影响，比如用户当前的指令语气和正在进行的操作流。
换句话说，模板不是代码，没有一个确定的执行路径。它更像一份入职培训手册，能显著提升表现的下限，但不能保证每一次行为都严格一致。所以对于真正零容忍的规则，不要只依赖提示，要用 hooks 和权限控制从机制上拦截。
6.4 定期"体检"比一次性建设重要得多
模板维护有个残酷的现实：它和代码一样会腐化。技术栈升级、团队规范调整、新踩的坑要补充，任何一个环节没跟上，模板就会逐渐变成误导人的历史文档。
我现在每两个礼拜做一次"模板体检"：拿当前模板初始化一个临时项目，跑几个标准场景，看看模型是否能按预期工作。整个过程二十分钟，能提前发现很多问题。
6.5 几个我反复验证过的实操心得
最后分享几个零散但实用的经验：
- 全局 CLAUDE.md 只写稳定偏好。比如"默认用中文回答""复杂操作前先说计划"。凡是可能为某个项目定制的条目，一律下沉到项目级文件。
- 命令模板里加参数示例。
argument-hint里写清楚"例如/review src/utils"，实际使用率和正确率会明显提高，团队里的新手拿到就知道怎么用。 - 把模板当作代码来 review。每次改通用模板，走正常的变更流程、更新 CHANGELOG、同步给团队。一旦走了非正式流程，模板改起来没有记录，过两个月就没人知道它怎么变成现在这样了。
我对claude-code-templates这套工作流的最终体会是：它的核心不是把规则写得多完美，而是建立一条从"经验"到"资产"的管道。单个项目里偶然发现的好规则是经验，沉淀进模板后它就是资产，能跨项目、跨人地复用。只要你不把模板当成一次性产出，而是当成一个需要持续维护的项目，它带来的回报会远远超出搭建时那点成本。
原理与MATLAB实战：从IMF到希尔伯特谱)