写代码这几年我越来越依赖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装上业务流程的外骨骼。我现在每天的工作方式已经变成了理解任务、判断场景、在终端输入一条斜杠命令、审核输出内容。重复性的提示词组织劳动降到最低精力都留在最重要的判断和决策上。模板这件事花费在设计与迭代上的时间大概在两周内就完完全全赚回来了。