我是在第三个项目里，把同一套需求分析、代码审查、重构指令重新敲到第四遍的时候，才真正意识到 claude-code-templates 这个东西的价值。之前我跟很多人一样，觉得让 Claude Code 干活不就是把需求讲清楚吗？后来发现，讲清楚一次容易，次次讲清楚很难；自己讲清楚容易，让团队成员也讲清楚更难。Claude Code 本身的推理能力确实强，但它有个特点——你输入什么质量，它就还你什么质量。输入里缺的东西，它不会凭空补，补了你也未必知道它补得对不对。
模板库就是把这部分"讲清楚"的成本一次性预付掉。我自己的经验是，做完一套像样的模板体系之后，同一个功能需求的开发时间大概能省下四分之一到三分之一，而且产出结构稳定得多，代码审查环节几乎不用再跟模型反复拉扯"你要不要看看你自己刚才写的那段是不是跑偏了"。这篇文章就聊聊我搭建 claude-code-templates 的一套完整思路：模板放在哪、长什么样、怎么跟 Skills 和 Commands 联动、以及我踩过的那些坑。
1. 从一堆 Prompt 到一套模板库：我的整理思路
1.1 没有模板时，Claude Code 用起来是什么感觉
先说痛点。刚开始用 Claude Code 的时候，我的工作模式是：想到什么需求就当场打一段话，比如"帮我给用户模块加个导出功能"，然后看它输出。结果经常出现几种情况：
第一种，它默认的假设跟项目实际架构不一致。项目里明明用的是组合式仓库加 pnpm workspace，它上来就给你往单包里塞代码；明明测试框架是 vitest，它可能按 jest 的习惯去写断言。
第二种，每个人的描述颗粒度差异太大。我描述需求喜欢讲业务背景和价值，同事习惯直接上技术方案，另一个同事又只会说"做个按钮"。同样的模型，同样的代码库，不同人来用，产出的东西完全不是一个水平线。
第三种，多轮对话里的指令漂移。一开始说好的"不要动公共 API"，聊着聊着模型就开始顺手改了一个公共函数的签名。倒不是它不听话，是它真的会忘——上下文越长，早期约束被稀释得越厉害。
这些问题其实都不是模型能力问题，而是"输入规范"问题。代码库的规范写在文档里，模型的规范却得靠每次对话重新建立，这是最消耗意志力的事。
1.2 模板到底在解决什么问题
我把模板解决的问题归纳成四类：
- 输出稳定性：同样的任务描述，用模板和不用模板，结果差异可以非常大。模板把"必须考虑的角度"和"必须遵守的边界"写成显式约束，模型就不需要每次都靠猜。
- 上下文效率：模板不是一个一个完整 prompt，而是一套分层规则文件，只有相关的部分会被加载。项目级规则进项目，全局风格进全局，子目录细节进子目录，模型看到的上下文更少但更精准。
- 协作基线：团队用同一套模板，等于所有人（包括 AI 在内）共享同一个默认值。你不必担心新人把需求描述得特别天马行空。
- 知识沉淀：每次踩坑之后的修复经验，都可以固化成一个规则条目或模板片段，下次直接复用。
我常打一个比方：模板之于 Claude Code，就像代码风格配置之于编辑器。编辑器本身能写代码，但没有统一的格式化规则，十个人写出来的东西就是十个样。模板解决的就是这个"样的统一"问题。
1.3 我的整理原则：先收敛，再固化
刚开始整理模板，我犯过一个方向性错误——想一次性把什么都塞进模板，结果模板本身比需求还长。后来我给自己定了几条原则：
- 先记下反复出现的任务类型，再为它写模板。如果一件事只出现过一次，先不写模板，只写备忘。出现过三次以上，才值得固化。
- 模板只写"必要约束"，不写"正确性主张"。比如不要一上来就规定"所有函数必须小于 30 行"，而是把这类问题留给你自己判断，模板只负责提醒"检查一下有没有超长函数"。
- 模板是活的，每两到三周要修订一次。尤其是团队规范变化、依赖升级、目录结构调整时，旧的模板条目会变成噪音。
这个原则在后面每一层模板设计里都在起作用。
2. CLAUDE.md 的三层结构：全局、项目、子目录
2.1 全局层：~/.claude/CLAUDE.md 存通用习惯
Claude Code 支持在多个层级放 CLAUDE.md 文件，它们在每次会话启动时按顺序被读取。最顶层是~/.claude/CLAUDE.md，也就是用户级全局文件，放那些在所有项目里都成立的东西。
我全局层放的内容大概有五类：
- 通用工作方式：比如"在动手改代码之前，先解释你的计划"、"遇到不确定的需求假设，主动提出三个澄清问题"。
- 代码风格默认值：比如命名习惯、注释语言、提交信息格式。
- 通用技术约束：比如"除非明确要求，不要使用未经讨论的第三方依赖"。
- 与 AI 协作的偏好：比如"分步实施，每完成一个阶段就停下来等待确认"。
- 常见禁忌清单：比如"不要删除看起来多余的代码，除非你确认它没有被引用"。
注意，全局层不能放跟具体项目强相关的规则。比如某个项目规定 commit 必须带 jira ticket 号，这种就不应该进全局文件，否则换个项目模板还在，反而成了干扰。全局层的定位是"跨项目通用的协作协议"，不是"万能规则表"。
2.2 项目层：让规则贴近真实代码库
项目根目录的CLAUDE.md是第二层，也是我投入时间最多的一层。它负责做三件事：
第一，交代技术栈与目录结构。我通常会在开头写一段类似这样的话："这是一个 pnpm workspace 的 TypeScript 项目，核心目录为 packages/core、packages/web、packages/api。新增代码优先放 packages 内部，不新增顶层目录。"模型读完这段，比读一遍 README 更清楚该怎么落位。
第二，标注关键决策与既有约束。比如"数据库迁移统一通过 drizzle-kit 生成"、"所有对外 API 必须通过网关层暴露，业务服务之间不允许直连"、"UI 组件库使用 xxx，不要自造组件"。这些信息如果不在模板里，模型会在错误的抽象层次上做决策。
第三，定义任务执行时的默认流程。我写的是"任何涉及多文件改动的任务，先列出改动清单再由你确认；测试必须在改动之后运行相关用例；涉及接口变更时，同步更新 OpenAPI 文档"。这比让模型自由发挥靠谱得多。
项目层模板要控制在一个合理的信息密度内。我的经验是一份 80-150 行的 CLAUDE.md 基本够用，超过 200 行就说明你把太多"一次性细节"写进去了，反而稀释了重点。
2.3 子目录层：把模板落到具体角落
第三层是子目录里的CLAUDE.md，Claude Code 在读取文件时会自动带上当前操作目录下找到的这个文件。这个机制特别适合两种情况：
一种是非常大的仓库，不同模块有各自的约定。比如docs/CLAUDE.md可以写"文档中所有截图路径必须来自 /assets/manual 目录，表格优先于列表表达结构"，api/CLAUDE.md可以写"所有接口必须包含校验中间件，错误响应统一为 { code, message } 结构"。
另一种是模板想要以"局部重点"的形式存在。比如你可以把"重构这个目录时的注意事项"写进对应目录的 CLAUDE.md，这样模型一进这个目录就会自动带上这些约束，而不会在全项目范围内被强制执行。
我实际使用中发现，子目录模板对于大型单体仓库尤其有效。因为它让模板的粒度从"项目"下放到了"模块"，既不会像项目级规则那样一刀切，也不用每次会话里手动粘贴一堆该模块的特殊说明。
2.4 三层模板的叠加顺序与冲突规则
弄清楚加载顺序非常重要。Claude Code 的规则合并大致是：全局 CLAUDE.md 先加载，项目根 CLAUDE.md 随后，再按上下文读取子目录的 CLAUDE.md，三者叠加，后读取的规则对同一话题具有更高的优先级。
这个设计意味着你可以用项目层"覆盖"全局层的不适条款，用子目录层"覆盖"项目层的粗粒度条款。我实际维护模板时就合理利用了这个特性：全局层写"默认使用英文提交信息"，但某个项目的 CLAUDE.md 里写"提交信息使用中文"，那么在这个项目里中文规则生效。全局层没必要为个别项目改来改去。
还有一个容易漏掉的细节：CLAUDE.md 支持用@path/to/file引入外部文件。我习惯把一些长模板（比如 PRD 模板、代码审查清单）放在templates/目录里，然后在根 CLAUDE.md 里用@templates/review-checklist.md引入。这样做的好处是主文件保持精炼，长模板按需加载。实测下来，这种按需引入方式对上下文的影响比全量塞进去小很多。
3. 好的模板长什么样：我沉淀下来的五个样例
这一节我直接把目前在用的几个模板文件结构放出来。大家可以直接拿过去改，不用从零开始。
3.1 需求与 PRD 模板：把"模糊需求"变成"可执行任务"
我给 Claude Code 做需求类任务的模板，核心是强制它先拆解再动手。它长这样：
## 角色定位 你是一名资深产品与工程负责人，负责把下面的原始需求整理成可执行的任务说明。 ## 输入 <原始需求粘贴在这里> ## 输出要求 1. 用不超过 5 句话描述需求的业务价值 2. 拆解影响范围：前端/后端/数据/文档/测试 3. 列出 3-5 个关键用户场景 4. 明确"不在本次范围内"的内容，防止蔓延 5. 输出一份分阶段实施计划（每阶段包含交付物与验收标准） 6. 标注风险点与需要进一步澄清的问题 ## 边界 - 不要开始写代码 - 不要假设技术选型，除非项目 CLAUDE.md 已规定 - 对于明显不合理的需求，直接指出并提供替代建议这个模板看着简单，但价值非常大。它是"需求分析提示词"，本质上是把模型从"编码助手"暂时切换成"产品顾问"。我自己用的时候还加了一步：让模型输出之后，我再回到对话里说"按这个计划开始第一阶段"，任务就非常清晰，不会跑偏。
3.2 代码审查清单模板：让 AI 担任固定视角的 Reviewer
代码审查是 Claude Code 特别适合的场景，但对模型来说如果没有约束，它会流于表面，只挑错别字和命名问题。我给审查任务定义了一个明确视角：
## 审查视角 你是一名严格的代码审查者，只关注会导致线上事故和长期维护成本的问题。 ## 必查清单 1. 数据流：输入校验是否完整，是否存在未处理 null/undefined 2. 错误处理：错误分支是否吞异常，是否返回对调用方有意义的错误 3. 并发与状态：是否存在竞态条件，共享状态是否被意外修改 4. 资源释放：数据库连接、文件句柄、定时器是否释放 5. 兼容性：本次改动是否破坏既有 API 或数据结构 6. 可测试性：新代码是否方便写单元测试，现有测试是否被破坏 ## 输出格式 将问题分为 P0（必须修复）、P1（强烈建议）、P2（可选建议）三档。 每个问题必须指出：文件位置、问题描述、修复建议。 不要输出赞美性评论，不要修改代码，只输出审查报告。用这个模板跑过几轮之后，我发现它抓出来的问题确实不一样。比如有一次模型发现了一个删除定时器遗漏的 bug，那是我自己 review 两次都没看到的问题。审查质量高的关键不在于模型更强，而在于清单给了它一个"必须逐个过"的框架。
3.3 重构与迁移任务模板：先定边界，再动手
重构类任务最怕的是模型"顺手优化"了不该动的东西。我用的重构模板专门在边界上做了严格约束：
## 任务 对 <模块路径> 进行重构，目标：<一句话描述，例如降低耦合度> ## 前置动作 1. 找出该模块的所有引用方，列出引用清单 2. 识别公共 API 面（被其他模块导入的符号） 3. 检查该模块对应的测试文件，确认当前测试覆盖情况 ## 执行约束 - 公共 API 签名不允许变化，除非你单独提出变更方案并等待确认 - 不改变现有行为，只改变内部结构 - 重构过程必须分阶段提交，每个阶段保持测试全绿 - 每次提交后说明本次改动的范围与验证方式 ## 完成后 - 运行完整测试，输出测试统计 - 输出重构前后对比摘要：删除的重复代码、拆分出的新文件、依赖关系变化这个模板最重要的一句话是"不改变现有行为，只改变内部结构"。没有这句话的时候，模型真的会在重构过程中顺手改逻辑，有时候改对了，有时候改错了，你根本来不及发现。
3.4 调试排查模板：让 AI 不要急着猜答案
调试场景里模型有个通病：看到一个报错日志，马上给出一个猜测，然后开始改代码。大部分猜测是错的，白白浪费时间。我的调试模板直接禁止它这样：
## 任务 复现并定位以下问题：<粘贴报错信息、复现步骤、相关日志> ## 调试流程（强制） 1. 先要求你列出 3 个以上的可能根因，按概率排序 2. 对每个根因，给出验证方法（打日志、单测、临时脚本等） 3. 选中概率最高的根因后，先做最小验证再动代码 4. 如果验证结果与预期不符，回到第 1 步重新分析 5. 定位到根因后，解释为什么会出现这个根因，再给出修复方案 ## 禁止事项 - 禁止在看到错误信息的前 5 分钟内直接给出修复代码 - 禁止修改与根因无关的代码 - 禁止用"可能是"这类模糊表述代替验证结果这个模板强制模型走"提出假设-设计验证-得到结论"的流程，像是在教它做科学实验。实际用下来定位成功率提升非常明显，因为它逼着模型把思考过程摊开，而不是只给你一个黑盒结论。
3.5 发版与变更日志模板：收尾阶段的稳定性保障
我最后一个高频模板是发版检查。它解决的是"模型改了 30 个文件，你要确定没有漏改配置、没有忘更新文档"的问题：
## 发版前检查清单 1. 列出本次变更涉及的所有文件清单 2. 核对 package.json / requirements.txt 等依赖文件是否有未记录的变更 3. 检查是否有新增环境变量，如果有，确认是否写入了 env.example 4. 检查数据库迁移目录，确认迁移文件与代码变更顺序一致 5. 生成变更日志，按 `feat(fix): 描述` 格式归类 6. 标注需要人工验证的回归场景 ## 输出 以表格形式输出：变更类型 | 文件 | 是否影响兼容性 | 是否需要人工验证这五个模板构成了一套从需求到发版的完整链路。我把它们统一放在项目的templates/目录里，既可以被 CLAUDE.md 引用，也可以单独作为文件让 Claude Code 读取。
4. 模板与 Skills、Commands、Hooks 的联动
4.1 Skills：把模板变成"可探测的能力"
Claude Code 的 Agent Skills 机制允许你创建一个包含 SKILL.md 和示例文件的能力目录，让模型在遇到相关任务时"发现"并加载它。把模板从 CLAUDE.md 里抽出来放进 Skills，是我整理模板库的第二阶段。
区别在于：CLAUDE.md 里的规则是被动加载的，模型每次都会读到；Skills 里的模板是主动发现的，只有任务相关时才会被读取。这意味着你可以把更长的、更专业的模板放进 Skills 目录，而不必担心每次都占据上下文。
具体做法是在.claude/skills/下建目录，比如：
.claude/skills/code-review/ ├── SKILL.md └── examples/ └── review-output-example.mdSKILL.md 里写清楚这个技能的使用场景、调用前置条件、以及上下文的组织方式。这样当模型看到一个"请帮我 review 这段代码"的任务时，它会自动去加载这个技能，而不是我每一次都手动粘贴审查清单。你会发现，Skills 是模板的自然延伸——模板是内容，Skills 是带触发条件的容器。
4.2 自定义斜杠命令：模板的快捷入口
Claude Code 支持自定义斜杠命令，放在.claude/commands/目录下。每个命令是一个 markdown 文件，文件名就是命令名。比如.claude/commands/prd.md对应/prd命令。
斜杠命令的价值在于把长模板的调用成本降到最低。我建了几个高频命令：
/prd：调用需求分析模板，然后用!让用户粘贴需求/review：对暂存区的代码执行审查清单/refactor：按重构模板开启一次重构/debug：进入调试排查流程/changelog：生成发版变更日志
一个很实用的细节是：命令行参数会以$ARGUMENTS变量的形式注入命令文件，所以你可以在模板里预留参数位置，比如/review $ARGUMENTS表示只审查某几个文件。这样模板既能全文复用，又能针对不同场景做参数化调用，灵活性大幅提升。
4.3 Hooks：在模板加载前后做自动化处理
CLAUDE.md 和 Skills 处理的都是"内容供给"，Hooks 处理的是"流程控制"。Claude Code 的 Hooks 可以在特定时机执行外部脚本，比如在对话开始前检查当前分支、文件变更后自动跑 linter、甚至根据当前 git 状态动态修改要注入的上下文。
我在模板库搭建后期加了一个简单的 Hooks 配置：每次会话开始前，脚本自动读取 git 当前分支名和未提交文件列表，写入一个临时文件，再通过 CLAUDE.md 的@引入方式让模型知道当前工作区的状态。这样模型开场的"猜测"就更少，因为它已经知道你在哪个分支、哪些文件动过。
Hooks 和模板的组合可以做到一件很有价值的事：按 git 变更动态生成提示上下文。比如脚本检测到本次提交涉及数据库迁移文件，就在临时上下文里追加一条"这次任务需要同时更新迁移文件和实体定义"。这比静态模板的覆盖面广得多。
4.4 MCP 与模板的关系：别把两者混为一谈
谈到 Claude Code 经常绕不开 MCP（Model Context Protocol）。这里我想澄清一个容易混淆的点：MCP 服务器解决的是"模型如何访问外部数据源"，模板解决的是"模型如何组织内部推理流程"，两者不是一个维度。
但它们在工程实践上会相遇。比如我接了一个数据库 MCP 服务，模型可以实时查表结构。这个时候，CLAUDE.md 里我就会加一条规则："在编写涉及数据库操作的代码之前，先通过 MCP 查询目标表的真实结构，再开始写代码。"模板负责规定"什么时候该用 MCP"，MCP 负责提供"实际的数据内容"，配合起来效果非常好。
所以我的建议是，搭建模板库的时候不要孤立地只看 prompt 文本，也要考虑你挂载的 MCP 工具、你写的 Hooks 脚本，把它们当作模板执行环境的一部分。
5. 模板翻车实录：我在实战里踩过的坑与排查思路
5.1 坑一：模板越长，模型越"敷衍"
我自己维护模板库时踩的第一个坑，是"规则越多，守得越差"。一开始我觉得约束越细越安全，写了一大堆条目，结果发现模型在长上下文里对模板的遵循度反而下降。后来查了很多资料才意识到，这与注意力分布有关——当 CLAUDE.md 超过一定长度，模型会对靠后的规则条目产生注意力稀释，简单说就是"记不住"。
我的排查方法是做了一次最小化实验：把模板内容砍掉一半，只保留最关键的前 10 条规则，然后在同样的任务上对比输出质量。结果出乎意料，精简版不仅输出质量没有下降，很多细节反而执行得更到位了。这让我确定了"少而精"的原则。
现在的做法是：把高频必守的规则控制在 10 条以内，放在 CLAUDE.md 开头；那些细节性、场景性的规则全部下沉到 Skills 或子目录模板里，按需加载。
5.2 坑二：全局模板污染项目任务
第二个坑来自全局层模板的"越权"。我曾经在~/.claude/CLAUDE.md里写了一条规定："所有代码必须包含完整的 JSDoc 注释。"当时是为了自己的一个主力项目服务的，结果切到另一个快速原型项目时，这套注释要求不仅没有帮助，反而让模型在每一小段代码后面都补了一大堆注释，产出噪音极大。
这类问题排查的线索很明显：当你发现新项目里的输出明显"过度设计"或"不符合这个项目的轻量风格"时，第一个要怀疑的就是全局模板。全局模板里只应该放那些你在任何项目里都认可的强规则，其他一律下放到项目层。
我后来专门检查了一轮全局模板，把里面所有带"技术选型倾向"的条目都删掉了，只保留了协作方式相关的规则。这样它在任何项目里都不会成为干扰源。
5.3 坑三：模板和实际代码架构脱节
模板是静态的，代码库是动态的。我遇到过的最尴尬情况是：模板里还写着"项目使用 xxx 状态管理库"，但实际上这个库三个月前就被团队换掉了。模型拿着过时规则做决策，输出自然不对。
解决这个问题的关键思路是：让模板引用代码库的真实信息，而不是复制一份静态事实。我在 CLAUDE.md 里不再写死"状态管理库用 xxx"，而是写"packages/web/src/store/ 目录下的状态管理方案请先阅读该目录的 README 再动手"。这样即使代码库内部更新了，模板的指示仍然有效，因为它指向的是一个可以被模型现场读取的真实文件。
同时我养成了一个习惯：每次代码库做大版本升级或目录重构之后，顺手过一眼 CLAUDE.md、Skills 里的示例文件，把过时的路径和描述更新掉。这个维护动作不复杂，但非常重要。
5.4 坑四：团队协作时的模板漂移
当 claude-code-templates 被团队共享以后，出现了一个新的问题：大家各自在自己的分支里改模板，过了一个月，模板库出现了十几个互相冲突的版本。有人加了一条规则，另一个人改了同样位置的措辞，merge 的时候也没有人认真检查语义冲突。
这个问题我目前的解法是：
- 模板库单独作为一个 Git 仓库维护，而不是散落在每个项目里。
- 通过脚本或 submodule 方式同步到项目里，保证项目使用的是固定版本。
- 模板变更必须走 PR 流程，由一个固定的人 review，语义冲突在 PR 阶段就被发现。
- 模板里涉及"事实型信息"（目录结构、技术栈）和"规则型信息"（约定、禁忌）分开存放，事实型信息尽量引用真实文件，规则型信息才允许直接写。
这样做了之后，模板库的维护演进就变得有序了。它不是一潭死水，而是像普通代码一样有版本、有评审、有回滚。
5.5 我的排查方法论
最后说说我是怎么排查"模板没有生效"这类问题的。
第一步，判断是"没读到"还是"读到了但没遵守"。如果模型完全表现出不知道某条规则，大概率是文件路径不对或者引入顺序有问题；如果模型表现出知道但没执行，则是优先级或表述清晰度的问题。
第二步，做最小化验证。只保留一条规则，跑一次任务，看模型是否遵守。如果单条规则能生效，再逐步加回其他规则，定位是哪一层出了问题。这很像代码调试里的二分查找。
第三步，检查上下文长度。如果项目里的 CLAUDE.md 太长了，模型在它之后又读了很多对话内容，早期规则就会被冲淡。这时候把长模板改成按需加载（Skills 或@引入）就能解决。
6. 让模板库持续进化的三个习惯
6.1 每次任务后回填"模板缺口"
我现在有一个固定动作：每一次让 Claude Code 完成一个比较复杂的任务之后，如果中途发生过一次"模型明显不知道某件事"的情况，我会立刻判断——这件事是否值得写进模板。如果值得，我会在当天的模板库里补一条规则，并备注"补充于某次任务中的某个失误"。
这个习惯其实就是把每次使用中的隐性知识显性化。时间一长，模板库会越来越贴合你自己的项目和你自己的工作习惯，而不是一份干巴巴的通用规则表。
6.2 用 Git 管理模板版本
既然模板库已经是一个 Git 仓库，那就要像管理代码一样管理它。我重点关注三件事：
- 每次修改模板，都写清楚 commit message，比如"增加数据库变更前的表结构检查规则"。
- 对模板做标签化发布，项目端锁定版本而不是追最新，避免突然一个模板改动影响所有存量项目。
- 定期审视 diff，删除那些自己都记不住为什么要加的条目。如果一条规则无法在两周内对应到一个具体场景，它就可能是噪音。
6.3 模板要能"分级下放"
最后一点是关于模板的适用范围。我现在的模板库分三个等级：全局通用模板、项目级模板、技能级模板，对应不同的加载时机和上下文代价。新建一个项目时，我只需要复制项目级模板那一份文件，其余全部从全局和技能层自动生效，几乎不用改内容。
把模板做成这个粒度之后，新项目上手 Claude Code 的成本就变得非常低了。团队里任何人接手，都默认拥有同样水平的"AI 使用配置"，不需要每个人自己去摸一遍最佳实践。
从我个人的实际体会来看，Claude Code 本身的水平已经很高，真正拉开使用效率差距的往往不是模型的强弱，而是你给它提供的上下文环境。一个结构清晰、按需加载、持续更新的模板库，就是这个环境里最重要的那一块地基。它不会让你的 AI 助手变得无所不能，但它能让 AI 助手在每个项目里都"像样地干活"，而这恰恰是我认为这个工具最值得投入打磨的地方。
详解：内存布局、性能陷阱与最佳实践)
