写代码这几年，我越来越依赖Claude Code做日常开发，但用得越深越发现一个尴尬的事实：同样一个工具，有人用它十分钟搞定一次代码审查，有人却要反复对话三四十轮才能拿到像样的结果。差距不在模型能力，而在你会不会给它一套清晰的"工作指令"。这个 claude-code-templates 项目，说白了就是我把自己在实战中反复打磨出来的提示词模板统一收拢、归类、做成可直接复用的一套方案。这篇文章就把我的设计思路和踩坑记录完整摊开，希望能给那些"每次都要重新组织语言"的开发者省下大量时间。
1. 模板到底是什么：先想清楚问题的本质
1.1 直接裸用Claude Code的痛点
很多人的Claude Code使用习惯是：打开终端，输入claude，然后开始一句一句描述需求。"帮我看看这个文件有没有问题""这个函数能优化吗""给我写个测试"，看起来没问题，但实际用起来效率极低。
我举个例子。你想让Claude Code审查一个改动很大的pull request，如果你只是笼统地说"帮我审查一下代码"，它会按照自己默认的理解去执行，可能重点看了格式、顺手找了几处变量命名问题，但完全没有针对你项目的并发安全、事务边界、异常链路给出有效反馈。不是模型不行，是你没有告诉它关心的焦点是什么。
还有更头疼的：Claude Code在同一目录下是有记忆的，每次会话的上下文状态会延续，但当它被大量无关的对话记录填充之后，输出的质量会肉眼可见地下降。你会发现越聊越偏，很多提示词在对话长度上来之后开始被遗忘，模型的行为前后矛盾。
模板解决的就是这两个核心问题：把"每次重复描述需求"变成"一句话调用标准流程"，同时通过精心设计的提示词结构，让模型在较短的上下文内就理解任务背景、约束条件和输出格式要求。
1.2 模板和普通提示词的本质区别
很多人把模板简单理解成"一段写得比较长的提示词"，这个理解不准确。一个真正可用的Claude Code模板，至少要包含五个层面的设计：
- 角色与目标定义：告诉模型它此刻扮演什么角色、要达到什么最终效果
- 项目上下文注入：关键路径、技术栈、已有的代码规范，避免模型自行猜测
- 任务边界约束：哪些事情必须做、哪些事情明确不做，防止模型"自由发挥"
- 输出格式要求：明确的交付物结构，例如先输出问题清单，再给出修改建议
- 自检与质量门槛：要求模型输出前完成一轮自我验证，降低幻觉概率
这五个层面缺一不可。缺少角色定义，输出语气和立场不稳定；缺少边界约束，模型会顺手改动你根本不想让它碰的代码；缺少输出格式要求，它会写一大堆你懒得看的分析文字。
我自己早期做过一个错误示范：写了一个"代码审查"模板，洋洋洒洒几百字，效果却很差。后来分析发现，我只告诉模型"分析问题"，却没有告诉它"哪些属于必须报告的高优先级问题"。于是它事无巨细地把所有小问题全部列出来，真正致命的架构问题反而被淹没在海量文字里。
2. 模板体系设计：我是怎么组织这些模板的
2.1 按开发场景做第一层分类
我在长期使用中总结出的一个原则：模板划分的粒度，要看你的实际使用频率，而不是理论上的功能边界。过于粗放的模板（比如只有一个"通用开发助手"）等于没有模板；过于细碎的模板（比如"修复某一个具体报错"）又会让你维护几百个文件，得不偿失。
目前我的模板仓库按场景分成这几大类，每个大类下再细分几个模板：
- 代码审查类：单文件审查、PR整体审查、安全专项审查
- 重构优化类：函数级重构、模块级重构、性能优化分析
- 测试辅助类：单元测试生成、集成测试方案设计、测试数据构造
- 文档与设计类：接口文档生成、架构设计评审、技术方案撰写
- Debug排查类：异常栈分析、问题复现路径设计、Root Cause分析
每一类之间不要共用太多内容，但底层的"上下文说明区"和"输出原则区"可以抽象成公共部分，避免模板之间互相矛盾。
2.2 模板的物理存储与调用方式
Claude Code的模板调用，目前我常用的有三种方式，各有适用场景：
方式一：CLAUDE.md 全局/项目级指令文件
CLAUDE.md 是 Claude Code 启动时自动加载的说明文件，可以放在用户全局目录（影响所有会话）或者项目根目录（只影响当前项目）。适合放那些"永远不变的背景信息"：技术栈、目录结构说明、编码规范、常用的禁止事项。
比如说我的一个后端项目，CLAUDE.md里会固定写入：
技术栈: Go 1.22 + PostgreSQL 15 + Redis 7，不使用ORM，使用sqlc生成数据访问层。 目录约定: /internal/service 业务逻辑，/internal/handler HTTP接口层，/migrations 数据库变更。 代码规范: 错误必须包装上下文返回，禁止吞掉error；接口层不做业务判断；所有配置走环境变量。 禁止行为: 不要修改go.mod中的依赖版本，除非明确要求；不要迁移数据库结构，除非明确要求。有了这些基础设定，每个会话开始时模型就天然具备了项目背景，不需要我在每次对话里重复"我们项目用的是Go哦"。
方式二：Slash Command 自定义命令
这是我最推荐的方式。Claude Code 支持在.claude/commands/目录下放置 markdown 文件，每个文件对应一个斜杠命令。比如我创建一个.claude/commands/review.md，在会话中直接输入/review就能触发这个模板。
这种方式的好处是不需要复制粘贴长文本，一条斜杠命令直接拉起完整流程，而且每个命令文件里可以写清楚"我期望的输入参数"和"默认行为"。命令文件还可以引用其他文件，做到逻辑复用。
方式三：独立提示词文件 + 手动引用
有些模板并不适合做成斜杠命令，比如那些需要配合特定文件内容一起使用的长流程模板。这种情况我会把模板写成单独的.md文件放在templates/目录里，在对话中使用@templates/xxx.md引用，或者用cat命令手动读取贴上。
三种方式不冲突，我实际项目里三个都用：CLAUDE.md管身份和背景，slash command管高频操作，独立文件管低频复杂任务。
2.3 一个模板的基本结构框架
我写的每个模板，基本遵循同一个物理结构，这篇文章后面拆解具体案例时会反复看到它的影子：
- 触发条件说明：什么情况下应该用这个模板，输入什么参数
- 角色初始化：让模型进入特定工作模式，设定思维视角
- 上下文加载清单：需要模型读取哪些文件、关注哪些路径
- 任务执行步骤：按顺序执行的步骤，每一步有明确目标
- 输出交付格式：最终结果的组织形式和字段结构
- 质量校验标准：模型输出前必须满足的硬性条件
我在设计模板时反复提醒自己一件事：模板不是提示词越长越好。每增加一句描述，都会占用上下文窗口、增加模型的认知负担，甚至可能引入矛盾。能用三句话说清楚的事情，不要用十句。模板的每一行都必须有它存在的理由。
3. 核心模板逐个拆解与实操要点
这一节我把使用频率最高的几个模板拿出来逐帧讲解，每段都会包含完整的模板设计思路和实际使用时的注意事项。
3.1 代码审查模板：让模型关注真正重要的问题
代码审查是我用得最多的场景，但也是早期效果最差的场景。问题出在默认行为上：Claude Code默认的审查视角偏"语言教师"，会关注语法、命名、代码风格，而真正做Code Review的人关心的是正确性、可维护性、性能隐患和架构一致性。
于是我设计了这样一个审查模板的核心逻辑：
你是一名具有多年经验的资深代码审查者。你的任务不是挑语法毛病，而是识别会导致线上事故、维护困难、扩展性差的实质性问题。 审查时严格按以下优先级输出发现的问题： P0 - 会导致功能错误、数据损坏、安全漏洞或严重性能问题的缺陷 P1 - 在特定边界条件下可能出错、或未来必然需要返工的设计问题 P2 - 可维护性、一致性、可测试性方面的改进建议 P3 - 风格类、非阻塞的轻微建议 输出格式要求： 按优先级分组列出问题，每个问题必须包含文件路径、行号、问题描述、严重性判断理由、修复建议。 所有建议必须可以执行，禁止输出"建议优化""请注意"之类的空话。 如果没有找到某个优先级的问题，明确写出"无"，不要编造。这个模板的关键点在于优先级分组 + 位置定位 + 禁止空话。实际执行下来你会发现，模型的输出从零散的"读后感"变成了结构化的审查报告，可以直接粘贴到PR评论里。
但这里有个陷阱我必须提醒：Claude Code审查代码的质量强烈依赖于它能否准确读到文件内容。如果PR涉及多个文件，一定要在模板中明确列出所有需要读取的文件路径，而不是让它自己猜。我在实际项目中遇到过模型漏看关键文件然后给出大段无关分析的情况，就是因为我没有把文件清单完整给它。
另一个心得是：审查模板不要写"请检查是否有安全漏洞"这种口号式内容。安全范围很大，你不如直接告诉它"特别关注用户输入是否经过校验、SQL是否参数化、敏感信息是否出现在日志中"，聚焦后的审查效果比泛泛而谈高一个数量级。
我在模板末尾增加了一条自检要求：
在输出最终审查结果之前，请先自检： 1. 是否每个P0级问题都给出了具体的行号和可复现路径？ 2. 是否有因为未读取某个相关文件而导致的分析遗漏？如果有，列出需要补充读取的文件。 3. 修复建议是否足够具体？是否避免了"只需注意"之类的模糊表述？这段话看似简单，但对输出质量的提升非常有效。它强迫模型在给出结果之前先把"如果要让你给出的结论承担责任"的标准执行一遍。
3.2 重构模板：可控的代码变更才是好变更
重构模板的设计目标和代码审查完全不同。审查的产出是分析文字，重构的产出是代码变更。代码变更是有风险的，模板设计的第一优先级是让模型克制，而不是让它放开手脚改。
我的重构模板核心约束如下：
- 每次只处理一个明确的重构目标，禁止顺手修改无关代码
- 重构前后的行为必须保持一致，除非目标是改变行为
- 输出必须包含"修改前片段"和"修改后片段"的对照
- 涉及公共接口、导出函数签名变更时，必须明确提示影响范围
- 重构完成后运行相关测试的命令必须给出
一个实操中的例子：我需要把一段超过200行的函数拆分成多个小函数，模板中的任务描述写成这样：
重构目标：将 `processOrder` 函数拆分为多个职责单一的内部函数，整体逻辑保持不变。 约束： 1. 拆分后的函数必须放在同一个文件内，除非有充分理由需要跨文件。 2. 每个新函数的命名必须准确描述其职责，禁止使用`helper1`这类无意义命名。 3. 拆分过程中不得改变原有错误处理流程和事务边界。 4. 如果发现原函数中存在异常逻辑，先不要自行修复，在输出中单独列出"发现的问题"。 5. 输出内容包含：重构设计说明（新函数职责划分）、关键代码对照、需要执行的验证测试命令。这里有个设计细节值得展开：约束第4条，发现异常逻辑时先记录不修复。这是我踩坑踩出来的教训。早期模板没有这条限制时，模型经常在拆函数的顺手把业务逻辑改了。你以为它在做机械性重构，其实它把判断条件顺序调整了、把错误返回时机改变了，这些行为变化往往隐藏在看似无害的"优化"里，测试不仔细根本发现不了。加了这条约束之后，模型的输出明显更克制，异常逻辑被单独列在报告里，等我自己确认后再决定是否处理。
重构模板另一个重要的部分是对测试的强制要求。我会在模板里写明："如果项目中存在与修改区域相关的测试文件，请列出测试文件名；如果没有相关测试，必须明确告知并建议创建一个覆盖重构行为的测试。"这个要求能极大降低重构引入回归的风险。
3.3 测试生成模板：让模型输出可直接落地的用例
我一直认为，让Claude Code生成测试用例是非常适合的场景，但也非常考验模板设计。不写模板直接让它"给这个函数写单元测试"，它大概率会生成一个充满mock、但实际测不到关键分支的"样子货"。
我的测试生成模板包含几个核心要素：
- 被测对象的行为描述，包括输入范围、边界条件、异常分支
- 测试框架和项目的约定（因为不同项目的测试风格差异极大）
- 要求输出的测试代码遵循项目的命名规范和断言风格
- 用例设计必须覆盖正常路径、边界路径、异常路径三类
- 禁止生成无意义的断言（比如只断言"函数不报错"）
我举一个实际设计案例。项目使用Go语言，使用标准库testing加上testify断言库。模板会明确写成：
请基于以下被测函数生成单元测试： 被测函数: internal/service/checkout.go 中的 CalculateTotal 输入参数: items []CartItem, promoCode string 返回值: (total float64, err error) 要求： 1. 使用 Go 标准 testing 框架，断言使用 testify/require。 2. 测试表驱动风格：每个case包含名称、输入、期望输出、期望错误。 3. 至少覆盖：空购物车、正常多商品、促销码命中、促销码已过期、负数价格、超长商品数量。 4. 所有测试用例必须先声明输入构造，禁止为了测试方便而修改被测函数签名。 5. 测试输出只包含代码，不需要解释文字。注意第4条，禁止为测试方便修改被测函数签名，这也是一个典型的坑。早期的测试模板缺少这条约束，模型在发现函数难以测试时（比如参数太多、依赖未注入），会自己动手改签名，把依赖变成参数传进来。这看起来"解决了问题"，但破坏了公共接口，所有调用点都要跟着改，完全不可接受。
测试生成模板还有一个特殊之处：Claude Code生成的测试代码，有时候会"骗人"。我遇到过它生成的测试对任何输入都能通过的情况，比如把具体数值断言写成了assert.Greater(t, result, 0)，这种断言毫无价值。所以在模板末尾我加了一条："用例设计必须包含至少一个精确值断言，禁止只使用范围断言。"}
3.4 Debug与Root Cause分析模板：从"修好"到"搞清楚为什么坏"
Debug类模板是我后期才补上的，但它现在使用频率极高。核心原因是我观察到，很多人把报错信息扔给Claude Code直接要"修复方案"，模型确实能给出方案，但这个方案经常是治标不治本的。
我的Debug模板设计思路是强制模型先做根因分析，再谈修复：
你是一名DevOps和SRE背景的故障排查专家。面对一个问题时，你坚持先定位根因，再设计修复方案。 请按以下流程执行： 1. 收集信息：读取我指定的日志文件、相关源码文件、配置文件的对应片段。 2. 提出问题：如果信息不足以确定根因，必须列出你缺失的信息清单，而不是猜测。 3. 假设验证：基于现有信息给出最可能的2-3个假设，每个假设都要说明如何进一步验证。 4. 根因结论：明确输出你判断的根因，并说明理由链。 5. 修复建议：给出短期规避方案和长期修复方案，标注各自的成本和风险。 6. 预防措施：说明如何通过监控、日志、自动化测试来防止同类问题再次出现。 整个过程禁止直接跳到最后一步。如果信息不足，第2步是强制性的。强制模型"先列出缺失信息"这条，是Debug模板最有效的部分。因为现实中，用户给Claude Code的信息几乎总是不足的，最常见的场景是只给了一段堆栈、却没给相关源码和部署配置。如果不强制它先提问，它就会基于不完整的上下文给出一个"看似合理但实际错误"的猜测。
我印象很深的是一次线上订单超时问题排查。当时我大略贴了一个Redis连接超时的报错，如果按照之前的方式直接问"怎么修复"，Claude Code大概率会说"检查Redis连接配置"这种不痛不痒的话。用了Debug模板之后，它先列出了四个缺失的信息：应用层连接池配置是多少、Redis服务端是否存在慢查询、网络转发路径有没有超时设置、报错发生时QPS是否有突增。按照这个引导补齐信息后，我才发现根因根本不是Redis本身，而是应用层一个连接泄漏导致连接池被耗尽。
Debug模板输出的报告，我还额外要求字段：问题影响范围、复现概率、验证方法。这三个字段逼着模型区分"偶发问题"和"必然问题"，也逼着我自己去思考问题的可观测性。
3.5 文档与设计模板：从"能读"到"能评审"
文档类模板的相对简单，但有一个关键点经常被忽略：模型生成的技术方案、接口文档，质量如何验证？如果没有验证标准，它很容易生成一套"看起来完整、细看全是问题"的内容。
我用于技术方案设计的模板，有一个反复强调的硬性要求：
输出技术方案时，必须包含以下章节： 1. 背景与目标：要解决的问题、成功标准 2. 方案概述：技术选型、架构图描述、关键流程 3. 详细设计：模块划分、接口定义、数据模型变更 4. 兼容性分析：对现有系统的影响、数据迁移方案 5. 风险与备选：主要风险点及对应的备选方案 6. 实施计划：分阶段的任务拆解、预估工时 在输出方案之前，先自检以下问题： - 方案是否依赖任何未经验证的技术假设？如果是，请明确指出需要在实施前做的技术验证。 - 接口定义是否覆盖了调用方的所有需求？是否考虑错误码、超时、重试策略？ - 如果这是增量方案，回滚方案是什么？这个模板的核心，不是让Claude Code"能写方案"，而是让它站在方案评审者的立场生产方案。每次它试图省略某个章节时（比如漏掉回滚方案），我都会发现，因为审查方一定会问。有了模板的强制约束，模型产出的方案在可评审性方面提升了很多。
4. 从"能用"到"好用"：模板的调试与迭代经验
4.1 模板不生效的常见原因
很多人复制了一套模板却发现没效果，第一反应是"模板有问题"，但实际上大部分问题出在调用方式上。我总结过几个高频原因：
- 模板没有正确注入：Claude Code的上下文是分层的，命令模板和CLAUDE.md是两回事，存在目录不对或文件命名不对导致命令识别不了的情况。
/review命令识别不了的时候，先检查命令文件名是否需要.md后缀、文件放的路径是否为.claude/commands/。 - 模板与项目背景冲突：比如模板里写了"使用Jest编写测试"，但项目实际用的是Vitest。模型在会话中会优先遵循CLAUDE.md中的项目规范，如果两者矛盾，输出会变得不可预测。所以我通常把"测试框架、语言版本"这类项目相关信息放在CLAUDE.md，模板里只写"遵循项目CLAUDE.md中的技术栈约定"。
- 一次塞入太多内容导致上下文碎片化：模板指令在长对话中会被"稀释"（细心的读者会发现模型后续回复的语气和格式逐渐偏离模板要求）。解决方法是把关键约束放在对话最近的消息中，或者使用新会话配合模板重新开始。
还有一种更隐蔽的情况：CLAUDE.md 文件本身过长。官方并不限制大小，但太长的CLAUDE.md会占用模型的注意力预算，反而导致重要指令被忽略。我测试过不同长度的CLAUDE.md对输出质量的影响，超过200行的CLAUDE.md会让模板指令的服从度明显下降。建议把CLAUDE.md控制在一页以内，事无巨细的内容放到独立的规则文档里按需引用。
4.2 如何量化评估一个模板好不好用
模板是要迭代的，每次迭代前你要能判断"新模板比旧模板好"。如果只说"感觉效果变好了"，那评估就没法持续。
我在项目中建立了一套简单的评估清单，每次改完模板后在几个固定的测试任务上跑一遍，对照清单打分：
- 任务完成度：输出结果是否直接满足任务的核心目标（比如审查模板是否给出了可定位到行号的问题清单）
- 指令服从率：模板中的硬性要求有几条被执行，几条被忽略
- 废话率：输出中无关分析、空话、套话占比（这个可以人工粗略估算）
- 上下文效率：达到同等质量结果需要多少轮对话，Round数少则效率高
- 幻觉率：输出中出现的事实性错误数量（比如错误引用代码行号、虚构不存在的API）
我自己的经验：一份好的模板，在固定测试任务上的指令服从率应该达到九成以上，废话率低于两成。达不到，就继续迭代。请特别注意，一旦你开始用这个标准来审视模板，你会发现自己以前觉得"挺好用"的模板其实问题很多。
4.3 模板的版本管理
模板仓库本身也是代码，我在维护上完全采用常规软件工程实践：每个模板文件头部写明版本号、最后修改日期、设计意图。每次修改记录在commit message里。
Claude Code的命令文件还支持一个很实用的特性：可以在文件中用额外的分隔符区分"定义区"和"说明区"，其中"说明区"的内容会展示在斜杠命令的菜单提示中。我会利用这个特性来写触发条件说明，这样使用者在执行命令之前就知道需要准备什么材料。
举个例子，我的/review命令文件开头是这样的：
触发条件说明：对本次改动的代码进行结构化审查。使用前请确保当前分支的目标分支、改动文件列表已通过参数或对话内容提供。 --- 你是一名资深代码审查者...在斜杠命令菜单里，模型的提示会显示触发说明，使用者自然知道该怎么准备。这看起来是小事，但在团队协作场景里，它能显著降低成员的学习成本。
5. 模板写作的几个独家心得
5.1 负面示范比正面要求更有效
经验告诉我，模板中"禁止做什么"的分量，往往比"应该做什么"更重。原因很简单：ChatGPT类模型在面对开放式任务时，天然倾向于自由发挥。你告诉它"应该输出结构化的审查报告"，它可能还是会自由发挥；但你告诉它"禁止输出无具体行号的空泛建议"，它服从的概率就高得多。
我在所有模板中都加入了负面清单。审查模板有"禁止空话"，重构模板有"禁止顺手修改无关代码"，测试模板有"禁止无价值断言"，Debug模板有"禁止跳过根因分析直接给出修复方案"。这些负面约束节省了我大量的二次澄清时间。
5.2 让模板自己写模板
这个方法有点取巧：我会把现有模板作为示例喂给Claude Code，然后让它按照同样的结构，为新的任务场景生成一个新模板。因为模型对已有模板结构的理解能力很强，生成出来的新模板大体会合格，我只需要做少量调整和边界约束即可。
具体做法是：
请参考下面这个代码审查模板的结构和写作风格，为"性能优化分析"场景创建一个新模板。 要求： - 保留触发条件说明、角色初始化、上下文清单、任务步骤、输出格式、质量校验标准六段结构。 - 性能优化模板需要有"性能基线测量"这一环节，不能只做理论分析。 - 加入负面清单：禁止给出没有数据支撑的优化结论；禁止建议引入新的第三方库（除非明确要求）。 以下是参考模板： [粘贴已有模板]这么做的效率极高，我仓库里大约三成的模板是让模型草拟、我来审核定稿的。但注意一点：模型生成的模板经常不够"狠"，负面清单往往写得不到位，需要你来补充。
5.3 不要维护过大的模板仓库
最后提醒一个方向性问题。模板的价值的的确确来源于质量和复用，但不要陷入"收集癖"。天天写新模板、仓库里堆了上百个却大部分用不上，这是本末倒置。
我的原则是：一个模板如果连续两周没有被使用，就合并或删除。宁可在需要时重新花十分钟写一个，也不养一堆从不调用的僵尸模板。模板也要做减法，做精比做多重要得多。
维护一套贴合自己工作流的模板体系，本质上是在给Claude Code装上"业务流程的外骨骼"。我现在每天的工作方式已经变成了：理解任务、判断场景、在终端输入一条斜杠命令、审核输出内容。重复性的提示词组织劳动降到最低，精力都留在最重要的判断和决策上。模板这件事，花费在设计与迭代上的时间，大概在两周内就完完全全赚回来了。
