我是在第三个项目里把同一套需求分析、代码审查、重构指令重新敲到第四遍的时候才真正意识到 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.mdClaude 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 经常绕不开 MCPModel Context Protocol。这里我想澄清一个容易混淆的点MCP 服务器解决的是模型如何访问外部数据源模板解决的是模型如何组织内部推理流程两者不是一个维度。但它们在工程实践上会相遇。比如我接了一个数据库 MCP 服务模型可以实时查表结构。这个时候CLAUDE.md 里我就会加一条规则在编写涉及数据库操作的代码之前先通过 MCP 查询目标表的真实结构再开始写代码。模板负责规定什么时候该用 MCPMCP 负责提供实际的数据内容配合起来效果非常好。所以我的建议是搭建模板库的时候不要孤立地只看 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 助手在每个项目里都像样地干活而这恰恰是我认为这个工具最值得投入打磨的地方。