先交代一个背景我把 Claude Code 当成日常写代码、做代码审查、重构旧项目的主力工具用了大半年。最开始那阵子我的用法跟大多数人一样——直接甩一句“帮我看看这个模块怎么优化”然后等结果。结果就是时好时坏同一个模型有时候给出非常漂亮的方案有时候又笨得让人怀疑是不是同一个产品。后来我把一次踩坑复盘的经验整理成了一个模板仓库给自己建了一套claude-code-templates问题才真正开始系统性解决。这篇文章不聊什么高大上的理论就讲清楚一件事怎么通过设计模板把 Claude Code 从“一个偶尔聪明的终端助手”变成“一个稳定靠谱的结对程序员”。适合正在用 Claude Code、但还没建立起自己模板体系的开发者也适合想给团队统一 AI 辅助编码规范的人。1. 模板到底解决什么问题为什么同样的模型配置不一样结果差一倍1.1 先搞清楚模板的底层机制要理解模板的价值得先理解 Claude Code 这类工具的工作方式。它本质上是一个“上下文驱动的代码代理”你给它的每一段指令它都会放入上下文窗口结合它读取到的仓库文件、对话历史一起推理出后续动作。这里的关键点是它每次能“记住”的东西是有限的。这里的限制不是指它能读多少代码文件而是指它的注意力会被分散。如果你在开局阶段就花掉大量 token 去理解一个含糊的任务后面真正干活时它就很容易丢失约束条件。模板的作用就是把这些约束条件提前压缩成一个结构化的“开场白”。你可以把它理解成给新同事准备的一份 onboarding 文档——如果新同事每次开始干活都要从零了解“这个项目是干什么的、技术栈是什么、目录怎么组织、代码风格怎么样、有哪些绝对不能碰的坑”那他的工作效率一定很低。模板就是把这些背景信息打包好让模型每次进入任务时都能快速进入“老手状态”。我在claude-code-templates里维护的核心资产其实不是某一段具体的提示词而是一整套“如何把项目经验和编码规范固化成模型可读文本”的方法论。这份方法论拆开来看就是三层结构项目基线CLAUDE.md、任务级模板斜杠命令、复用型流程模板。1.2 没有模板时我最常踩的四个坑先说说我在建立模板库之前实际踩过的坑。这些坑应该能引起不少人的共鸣第一个坑是上下文反复重述。每次开新对话我都要花几百个 token 重新描述项目背景、技术栈、目录结构。一开始还好随着项目变大描述本身变成了一套小作文。更尴尬的是描述写得不完整时模型会按自己的理解瞎猜然后生成一个跟项目架构完全不搭的方案。第二个坑是代码风格漂移。同一个项目里今天让模型写的工具函数是驼峰命名明天生成的就是下划线风格。因为我没有告诉它项目里既有代码的规范。这种漂移在单个文件里看不出来但拉取请求审查时那种“一眼就知道不是同一个开发者写的”感觉非常让人头大。第三个坑是约束条件被遗忘。有些项目有这个限制、那个限制比如“不能用某个依赖”“这个模块必须是纯函数”“日志必须走统一封装”。你开头说了模型可能开头记住了但任务一长它会慢慢“忘记”这些约束开始自由发挥。这不是模型问题而是我把约束放在了对话里而不是模板里让它变成了“可以遗忘的背景信息”。第四个坑是评审质量忽高忽低。让模型做代码审查时有时候它能抓到很隐蔽的并发问题有时候又只盯着缩进和命名说废话。后来我才意识到不是模型状态不好而是我给它的指令太模糊了。它不知道我到底想让它审查“正确性”还是“风格”还是“架构一致性”。这四个坑汇总成一句话不是模型的水平不行是我给它的上下文质量太差。模板要解决的就是这些问题。1.3 模板仓库的形态一个目录、一堆 Markdown 文件claude-code-templates看起来很简单就是一个目录里面放了一堆 Markdown 文件。但它的组织方式是有讲究的。我当前的仓库结构大概长这样claude-code-templates/ ├── CLAUDE.md # 全局基线通用编码规范、协作原则 ├── project/ │ ├── CLAUDE.md.template # 新项目基线模板 │ └── commands/ │ ├── review.md # 代码审查 │ ├── architecture.md # 架构评审 │ ├── breakdown.md # 需求拆解 │ └── debug.md # 调试排查 └── shared/ ├── prompts/ │ ├── refactor.md │ └── test-writing.md └── snippets/ ├── commit-message.md └── changelog.md这套结构遵循三个原则第一基线文件只放“每个任务都需要知道的事”第二命令文件只放“特定任务才需要知道的事”第三共享目录放“跨项目复用的事”。这样设计的好处是模型每次加载的上下文不会无限膨胀该知道的它都知道不该知道的它也不会被干扰。2. 模板体系怎么搭从项目级默认上下文到任务级命令2.1 第一层CLAUDE.md 项目基线CLAUDE.md是 Claude Code 的项目级“说明书”它会在每次对话启动时自动加载。这一层是模板库的地基地基没打好后面所有的任务模板都会跟着遭殃。我写的CLAUDE.md模板包含这么几个区块项目一句话简介用三行以内说清楚项目是干嘛的避免模型对业务目标产生误解。技术栈与关键依赖不列全部依赖只列影响架构决策的那些比如框架版本、ORM、消息队列、缓存方案。目录结构速览不是把所有目录都列出来而是标出“核心业务代码在哪、测试在哪、配置文件在哪”这几个模型最常找的地方。常用命令构建、测试、lint、格式化、运行单个测试文件。这个一定要准确不然模型会凭惯性猜一个 npm script。编码规范命名风格、格式化偏好、错误处理方式、禁止使用的反模式。架构约束哪些模块不能互相依赖、数据流方向、状态管理约定。这是最容易漏掉但最重要的部分。这里我给一个精简的示例我自己在新项目里会直接改着用# 项目订单服务 ## 概述 订单服务负责订单生命周期管理提供创建、支付回调、取消、售后等 REST API。 所有数据通过 MySQL 存储缓存层使用 Redis。 ## 技术栈 - Node.js 20 / TypeScript 5.x - Express 4.x Prisma ORM - 测试Vitest Supertest ## 目录速览 - src/modules/order订单核心业务逻辑 - src/modules/payment支付对接与回调 - src/infra数据库、缓存、消息队列封装 - tests集成测试 ## 常用命令 - npm run dev本地启动 - npm test跑全部测试 - npm run test:unit -- src/xxx.test.ts跑单个测试 - npm run lint代码检查 ## 编码规范 - 使用函数式组件风格避免 Class 组件 - 错误信息统一为英文错误码在 src/constants/errors.ts 中定义 - 禁止直接使用 any未知类型用 unknown 并做窄化 - 所有外部请求必须走 src/infra/http 封装不允许裸写 fetch ## 架构约束 - order 模块不得直接引用 payment 模块的内部实现只能通过支付服务接口调用 - 所有写操作必须在事务内完成且事务只能覆盖单一聚合根 - 缓存键必须按 src/infra/cache/keys.ts 中的规范命名写这个文件时最容易犯的一个错是把它写成“项目百科大全”什么细节都往里塞。我见过有人把整个数据库表结构都贴进去几百行的 CLAUDE.md结果模型每次都要加载一大堆跟当前任务无关的信息反而是负担。我的经验是CLAUDE.md控制在 150 到 300 行之间。如果超过这个量说明基线里混进了太多任务级内容应该拆出来放到对应的斜杠命令模板里。2.2 第二层自定义斜杠命令模板基线文件解决的是“每次都知道”的问题但实际工作里更多是“特定任务时需要一套完整的执行思路”。这就是自定义斜杠命令模板的用武之地。Claude Code 支持在项目的.claude/commands/目录不同版本也可能叫templates下放置 Markdown 文件文件名就是命令名。比如放一个review.md就能通过/review触发。文件里可以用 YAML frontmatter 配置描述信息、参数提示等元数据正文部分就是一段完整的提示词。我一开始只把这当成“给常用指令起个短名字”后来才发现它的真正威力在于它允许我把一整套任务执行方法论固定下来。比如代码审查我平时口头说“帮我审查一下这个文件”和通过/review触发看起来差不多但实际效果天差地别。原因在于斜杠命令模板里的内容不是一句模糊的请求而是一套完整的执行框架先读哪些文件、按什么维度检查、输出格式是什么、哪些问题优先级最高、遇到不确定时怎么处理。这些框架性的内容如果每次都用自然语言说一遍自己都觉得啰嗦更别提说清楚。但放在模板里它变成了一个稳定的、可复用的“流程函数”。2.3 第三层跨项目复用模板做了几个项目之后我发现很多模板是可以跨项目复用的。比如代码审查、需求拆解、调试排查这类通用型任务模板它们的核心逻辑跟具体项目无关只需要在运行时动态注入项目特定的上下文。所以我的模板库设计成了两层复用机制。第一层是用户级命令目录放在~/.claude/commands/下对所有项目生效适合放那些纯方法论的任务模板。第二层是项目级命令目录放在项目的.claude/commands/下只在当前项目生效适合放那些跟项目架构绑定的专用任务模板。这两层可以同时生效优先级的处理方式是项目级覆盖用户级。这个机制让我既能保持通用模板的一致性又能为每个项目定制特殊逻辑。2.4 模板里的变量与动态内容模板不应该是死文本。我在设计claude-code-templates时特别注意在模板里留出“动态插值”的位置让模板既能提供框架又能接收当前任务的个性化信息。一种做法是依赖斜杠命令的参数。比如/review后面可以直接跟文件列表模板里预留一个“审查目标”的占位让用户输入的文件名作为参数传入。另一种做法是在模板正文里用“请先读取 XXX 文件再结合当前变更”这种指令让模板自己决定什么时候拉取项目信息。这里要特别强调一个设计原则模板不应该把项目信息写死。比如你在模板里写“本项目是订单服务使用 Express”那这个模板就只能给订单服务项目用。正确的方式是写“先读取项目根目录的 CLAUDE.md再结合当前变更上下文”让模板在运行时自己去获取项目信息。这样同一个模板才能在不同项目里安全复用。3. 实操四套可直接抄作业的高质量模板这一章我把仓库里最常用的四套模板完整展示出来并解释每个关键部分的设计意图。你可以直接复制改造成自己用的版本。3.1 代码审查模板让模型从“找茬”升级为“按维度体检”我最早做的模板就是代码审查。因为我发现直接让模型审查代码时它给的反馈经常是“这个函数有点长建议拆分”这类泛泛而谈的意见而不是真正的技术债信号。后来我把审查任务拆成了五个维度每个维度对应一组明确的检查项正确性有没有边界条件没处理、空值风险、异步竞态。安全性有没有注入风险、敏感信息泄漏、权限校验缺失。性能有没有不必要的循环、重复查询、大对象持有。一致性是否符合 CLAUDE.md 里的命名规范和架构约束。可维护性有没有难以理解的逻辑、缺少必要注释、测试覆盖不足。模板正文.claude/commands/review.md--- description: 对当前变更做系统化代码审查给出可执行的修改建议 argument-hint: 文件或范围说明 --- 请以资深开发者的身份对本次变更做一次系统性代码审查。 第一步先读取项目 CLAUDE.md确认项目的编码规范和架构约束。 第二步定位发生变更的文件理解变更动机而不只是看 diff 本身。 第三步按以下维度逐一检查每个维度给出独立的结论 1. 正确性边界条件、空值处理、并发安全、错误处理路径 2. 安全性注入风险、数据校验、敏感信息、最小权限 3. 性能N1 查询、重复计算、不必要的大对象生命周期 4. 一致性命名、格式化、错误处理方式是否与项目既有代码一致 5. 可维护性复杂度是否可理解、测试是否有有效断言、是否有过时注释 对每个维度输出 - 发现的问题清单按严重程度排序 - 每个问题的位置文件行号 - 修改建议尽量给出可以直接落地的写法 最后给出总结评级通过 / 需小幅修改 / 需大幅修改。 如果对某个问题没有把握明确标注“存疑”不要编造结论。这套模板的核心设计意图一是把“审查标准”前置让模型知道从哪些维度看问题二是把输出格式固定下来方便我直接处理结果。以前模型给一堆发散的长文我要自己提炼重点现在它输出的就是可以直接转给同事的评审意见。使用时的注意事项/review src/modules/order/service.ts这样调用。如果审查对象是一整个 PR我会先描述 PR 的上下文再用模板。模板虽然比我口头说的长很多但因为加载的是固定的高质量指令实际消耗的 token 是值得的。3.2 架构方案评审模板大改动之前先让模型当一次“假想敌”架构评审比代码审查更难模板化因为每次评审的颗粒度和行业背景都不一样。但我在实践后发现无论什么架构方案评审时都绕不开几个核心问题约束条件有没有被违反、权衡有没有被充分考虑、备选方案有没有被公平对比、风险有没有被识别。所以这套模板的思路是让模型当一次“有立场的假想敌”而不是泛泛的顾问。模板正文.claude/commands/architecture.md--- description: 评审一份架构设计或技术选型方案评估可行性与潜在风险 argument-hint: 设计方案文档路径 --- 请以系统架构师的身份评审我给出的架构方案。 先阅读以下上下文 1. 项目 CLAUDE.md 中的架构约束 2. 当前方案的描述文档若提供了文件路径请先读取 3. 方案中涉及的关键依赖的技术文档或接口定义 然后按以下框架输出评审意见 一、约束检查 - 方案是否违反 CLAUDE.md 中已有的架构约束 - 是否引入了项目技术栈之外的新依赖理由是否充分 二、权衡矩阵 - 方案在哪些维度上做了取舍如一致性 vs 可用性、开发效率 vs 运行性能、简单性 vs 扩展性 - 权衡的方向是否合理有没有被忽略的关键维度 三、备选对比 - 是否公平对比了至少一个备选方案 - 方案被否掉的原因是否成立有没有因为“惯性”而排除某些选项 四、风险清单 - 列出实现该方案的主要风险点按概率和影响两个维度评估 - 每个风险给出一个可行的缓解措施 五、分阶段落地建议 - 如果同意该方案给出分阶段实施建议 - 如果不同意明确指出阻塞项是什么 最后用一句话给出结论建议采纳 / 建议修改后采纳 / 不建议采纳。我通常在两种场景下用这套模板一是自己拿不定主意时让模型扮演一个挑剔的评审者二是在正式评审会之前用它的意见帮我预先补齐方案的漏洞。实测下来最有价值的输出是“风险清单”和“权衡矩阵”部分模型往往会提出一些我没想到的边界情况。3.3 需求拆解模板从模糊需求到可执行任务的翻译器需求拆解是我用 Claude Code 做的最“非代码”的工作但也是收益最大的。很多任务执行得不好不是因为写代码的环节有问题而是因为需求本身含糊不清。我的拆解模板的设计思路是把“一句话需求”逐步展开成任务清单每一步都补上模型执行时必要的信息。模板正文.claude/commands/breakdown.md--- description: 将需求拆解为可执行的任务清单输出到指定文件 argument-hint: 需求描述或需求文档路径 --- 请将以下需求拆解为可执行的任务清单。 需求[用户在此粘贴需求内容] 拆解步骤 第一步明确验收标准。如果需求里没有明确“完成”的定义列出你识别出的关键验收点并标注哪些需要向需求方确认。 第二步识别影响面。列出该需求会涉及的模块、接口、数据表、配置文件并检查是否有既有代码可以直接复用。 第三步拆分任务。每个任务控制在“一个工作会话可完成”的粒度按依赖关系排序标注哪些任务可以并行。 第四步补充技术注意事项。对每个任务给出该任务特有的实现约束比如需要遵循哪个既有模块的约定、需要处理哪些边界情况。 第五步识别测试策略。对每个任务说明应该补充单元测试、集成测试还是手工验证。 输出格式 - 任务清单按优先级排序 - 每个任务包含目标描述、涉及文件、依赖前置、完成定义 - 风险提示区可能阻碍完成的不确定项使用这套模板后我做需求评审的节奏加快了不少。尤其对于前后端同时开工的项目拆解出来的“涉及文件”列表直接可以作为团队分工的依据。3.4 调试排查模板让模型先当侦探再当医生调试是最容易被低估的模板场景。很多人遇到 bug 时直接问模型“这段代码为什么有问题”模型给一个猜测性的答案你去验证发现不对再问一次。这样反复几次效率极低。我做过的最有用的调试模板是在模板里强制模型先收集证据、形成假设再动手改代码。模板正文.claude/commands/debug.md--- description: 系统化排查问题根因给出可验证的修复方案 argument-hint: 问题描述 --- 请帮助排查以下问题[用户在此粘贴问题现象] 你的排查过程必须严格按以下步骤执行 第一步信息收集。先读取相关代码文件、日志、测试用例。列出你收集到的所有关键信息包括错误信息、复现步骤、最近一次可正常工作的变更。 第二步提出假设。基于收集到的信息列出至少两个可能的根因假设。对每个假设说明为什么它可能成立以及如何验证。 第三步验证假设。用代码阅读、加日志、跑测试等方式验证假设。每轮验证都要给出结论支持还是推翻该假设。 第四步定位根因。在假设验证完成后指出最可能的根因并用一段话解释完整的因果关系链。 第五步给出修复方案。修复方案必须包含涉及文件、修改思路、需要补充的测试用例、验证修复效果的具体步骤。 强制规则 - 在没有完成第二步之前禁止直接给出修复建议 - 如果信息不足先明确列出缺少的信息而不是猜测 - 修复后明确指出该修复可能引入的新风险这套模板强行让模型“先侦探、后医生”从机制上避免了它一上来就输出不负责任的猜测。你看它没写什么神奇的东西但它把一个有经验的工程师做调试时的思维链完整地固化了。3.5 模板组合一次任务用多个模板模板不是只能单独用。我在执行一个较大的重构任务时经常这样组合使用先用/breakdown拆解任务然后用/review审查重构过程中生成的代码最后用/architecture评审整个改动方案是否符合项目架构。组合使用时有个小技巧我在CLAUDE.md里加了一条约定告诉模型它可以使用哪些斜杠命令、分别在什么场景下使用。这样模型在任务执行过程中如果发现需要审查某段代码它会主动建议“可以使用 /review 模板”形成自动化配合。4. 常见问题与排查技巧实录4.1 模板不生效路径和加载优先级排查我最开始搭建模板时遇到最多的问题是“明明放了文件但斜杠命令就是出不来”。排查步骤其实很简单但值得记下来首先确认目录路径。我见过不少人把命令文件放在了templates/而不是commands/目录下或者是忘了用文件名命名。Claude Code 读取的是特定目录下的特定命名规则文件名就是命令名文件后缀用.md。其次确认是项目级还是用户级。项目级命令目录在当前项目的.claude/下用户级在~/.claude/下。如果两边有同名命令项目级会覆盖用户级。遇到“改了模板但行为没变”的情况先检查是不是被另一个级别的同名命令覆盖了。最后是刷新问题。新建或修改命令文件后有时候需要在对话中重新触发一次或者重启会话让工具重新扫描目录。这个听起来很基础但真的容易忽略。4.2 上下文提示词膨胀模板越多加载越慢模板的价值是“让该知道的信息都知道”但如果你把太多模板内容全部塞进CLAUDE.md它就会变成性能灾难。每次对话启动都要加载大量文本挤占上下文窗口的可用空间。我的处理思路是分层设计前文也提到过CLAUDE.md只保留高复用、低变化的信息任务级信息全部放到斜杠命令里按需触发一次性任务要求则在对话里临时描述。具体数字上我的经验是CLAUDE.md加上斜杠命令的总量不应该让每次对话的上下文消耗超过整体上下文的四分之一。否则留给实际代码分析的 token 就太少了模型会变得“只看得到规则看不到代码”。4.3 模板输出质量不稳定问题多半出在“约束不收敛”有时候同一个模板连续跑几次输出质量差异很大。排查下来最常见的原因是模板里的指示语太宽泛比如“请检查代码质量”这种话模型可以用一万种方式理解。解决方法是像前文模板示例那样把任务分解成明确的步骤和输出格式用“第一步做什么、第二步做什么”来约束模型的工作路径。另一个技巧是给模型一个“输出模板”比如“对每个问题输出位置 问题描述 修改建议”这样模型会把自己的思维过程也结构化。我还在模板里加过一段“如果对某个问题没有把握明确标注存疑不要编造结论”。这一句看似不起眼但对抑制模型“自信地胡说”非常有效。4.4 团队协作时的模板冲突如果你在团队里共享模板会遇到另一个问题不同成员的经验和偏好不同有人觉得应该在CLAUDE.md里写“禁止使用 any”有人觉得这是过度约束。直接在共享仓库里改容易引发冲突。我的做法是建立“模板评审”机制模板文件本身要走代码审查流程重大改动先在仓库的 Issue 里讨论。模板和代码一样它也是需要维护的产品。谁往里加规则谁就要对这条规则的实际收益负责。有过一次惨痛教训有个同事在审查模板里加了一条“所有函数必须有 JSDoc 注释”结果模型在每次审查时都优先挑“缺注释”的毛病真正的逻辑问题反而被忽略了。那个模板运行了整整一周我才发现这个问题。从此以后我要求所有模板改动必须附带“这条规则能捕获哪些真实问题”的说明。5. 我的体会与经验最后分享三个我在沉淀claude-code-templates过程中的切身体会。第一模板的价值是积累出来的不是设计出来的。第一版模板根本不用追求完美先把最常用的两三个任务做成模板跑起来然后在实际使用中不断迭代。我现在的模板库是几十次改版后的结果每一版都是在真实任务中暴露问题后修正的。如果你第一次就试图设计一个完美的体系大概率会卡在设计阶段迟迟无法落地。第二模板维护要有“删”的勇气。大多数人的模板库问题是太少我的问题是时不时会膨胀。每隔一段时间我会检查一遍哪些模板已经很久没用了哪些规则在真实项目中从来没触发过该删就删该合并就合并。模板太多跟太少一样有害因为它会变成噪声。第三把模板看作团队知识沉淀的工具而不是自己的效率工具。当我把自己踩过的坑、总结的规范写进模板它就变成了团队所有成员都能享用的知识库。新成员加入时不用再从头摸索“这个项目为什么这么写”因为模板已经把这些约束讲清楚了。我现在的工作流里claude-code-templates已经不是一个辅助工具而是我的开发习惯本身。每次新项目初始化第一件事就是按模板创建CLAUDE.md每次开会评审第一件事是把方案丢给/architecture模板每次接到需求第一件事是跑一遍/breakdown模板。这套体系带来的改变比换一个模型版本、升级一套 IDE 插件都要明显得多。如果你还没开始搭建自己的模板库现在就可以从一份CLAUDE.md和一个/review命令开始。