做 claude-code-templates 这个项目之前我在 Claude Code 上的使用体验只能用薛定谔的质量来形容。同样是重构一个模块有时候它事无巨细地给我解释半天有时候又一句话带过直接甩代码同样是让 AI 审查代码有时候它给出了非常到位的并发隐患提示有时候却把精力放在修改变量命名这种无关痛痒的地方。这种失控感一度让我怀疑模型能力不够但后来我意识到问题不在模型在于我根本没告诉它按什么套路来。claude-code-templates 的核心就是一个提示词模板库把每次重复交代的角色、任务边界、输出格式、质量红线全部固化下来让 Claude Code 在接到任务的第一秒就进入专家状态。说白了就是给 AI 立规矩、定套路让它的输出不再是随机波动而是稳在一条基准线之上。这套东西适合已经在用 Claude Code 但觉得输出不够稳定的开发者也适合想系统提升 AI 编码质量、把 AI 用出高级感的人。接下来我会从模板的结构设计、几套可以直接抄作业的模板、在 Claude Code 里落地模板的三种姿势以及我调试模板过程中踩过的坑这几个方向展开。如果你是刚接触 Claude Code前两节可以帮助你建立骨架认知如果你已经踩过一些坑可以直接跳到第三节开始抄模板。1. 为什么要给 Claude Code 准备模板从裸聊到结构化1.1 没有模板时我踩过的坑先说一段真实经历。有段时间我频繁让 Claude Code 帮忙做代码审查用的方式是直接描述一句话帮我 review 一下这个文件。结果大家应该能猜到第一次它认真列出了十几个问题第二次面对同样规模的代码却只回了一句看起来没问题。这种不稳定不是偶发现象。问题出在三个方面一是目标漂移。没有模板时模型会自己在找bug、提建议、讲解原理、直接改代码这几件事之间随机游走甚至会出现先评论代码风格、再分析性能、最后变成教学这种四不像的输出。二是标准不统一。同样是审查第一次可能只关注逻辑错误第二次却重点看命名规范因为提示词里没有定义什么最重要。三是输出形态不可控。有时候给表格有时候给长文有时候直接给 diff我看得一头雾水。这三个问题叠加起来让 AI 工具的价值大打折扣。后来我把搜索到的几套开源 prompt 工程方法拿过来对比发现真正有效的做法只有一个不要每次重新写提示词而是维护一套固定的模板把对 AI 的期待全部写死在纸面上。1.2 模板的价值把通用助手变成岗位专家Claude Code 本身是一个很强的通用编码助手但通用也意味着没有棱角。如果你不告诉它今天扮演什么角色它默认会给你一个中庸的、各方面都沾一点的反馈。而模板的价值恰恰是把无棱角的通用能力塑造成特定场景下的专家行为。我举个例子。假设你要做一次接口兼容性审查没有模板的话 AI 会关注什么大概率是命名、注释、有没有语法错误。但如果你在模板里明确它应该关注旧调用方是否会被破坏、默认参数变更是否影响外部行为、返回值类型变更是否导致下游失败它的注意力就会被精准拉过去。同一个模型模板不同产出的含金量完全不同。所以在 claude-code-templates 里我做的第一件事不是堆数量而是把使用场景拆开代码审查、重构、单测生成、提交信息撰写、错误排查、技术方案设计、遗留系统文档梳理。每个场景一套模板每套模板都围绕让 AI 在一类任务上有持久稳定的专家表现来设计。提示模板不是万能药。如果你的场景是开放式头脑风暴、随便聊聊架构那反而是不套模板效果更好。模板的适用边界是任务边界清晰、质量标准可定义、输出形态可预期的场景。2. 模板的核心结构与设计思路2.1 一个合格模板的五个必备模块我早年看过不少 prompt 教程自己也拆过很多开源模板最后总结出一套五段式结构。是我认为目前最稳的写法也是 claude-code-templates 里所有模板的骨架角色定义开头第一句就要把 AI 的身份钉死。任务描述用清晰的语言界定本轮要做什么、不做什么。输入约定说明代码、文件路径、上下文信息如何给。这一块最容易被忽略但它决定了每轮交互时模板能不能接得住话。约束与禁区列出绝对不能做的事情、不能逾越的质量红线。输出格式指定用表格、清单、代码块还是 diff 输出并给出结构骨架。这五个模块不是随便堆砌的它们各自解决一个真实问题。角色定义解决风格漂移任务描述解决目标漂移输入约定解决话传不到位约束与禁区解决AI 自作主张输出格式解决解析成本过高。五件套齐全模板才是一个完整的工作协议而不是一句好听的提示词。2.2 角色定义与任务边界的写作技巧角色定义看似简单但很多人写得不对。差的写法是你是一个资深工程师好的写法是你是一位拥有十年以上后端开发经验、主导过大型系统架构设计、主要使用 Go 和 Python 的工程师擅长发现分布式系统中的并发隐患和故障恢复问题。区别在于细节锚点。锚点越具体AI 越容易激活对应的知识域给出的建议就越贴近真实专家。我常用的手法是在角色里嵌入三个要素年限与层级影响表达的权威感和判断力、技术栈影响举例和方案选型、过往项目类型影响关注点。任务边界这一块我踩过最大的坑是给了任务但没给反例。比如代码审查模板里写审查这个文件模型可能顺手开始关注代码风格于是我在所有模板里都加了不做某事的显式说明。例如审查模板里明确写不关注缩进、命名风格这类问题除非它们影响代码正确性。负面约束的作用往往比正面指令更明显这条经验价值极高。2.3 输出格式与约束条件的设计原则输出格式为什么要写死在模板里因为模型在自由发挥时输出的结构方差巨大。如果你需要的是能在 CI 里解析的审查报告它给你一篇散文你的自动化流程就断了。所以在 claude-code-templates 里我给每个模板都设计了固定的输出骨架。以代码审查模板为例输出格式固定为结论段、问题清单表、可选的改进建议段。问题清单表固定四列严重等级、位置、问题描述、修复建议。这样的结构有两个好处一是人眼扫读成本极低二是问题清单可以脚本化处理比如提取所有严重级别问题自动发送到消息通知。约束条件的写作原则是少而狠。不要列二十条纪律模型记不住那么多优先级。抓住两三条真正致命的要求即可。比如在重构模板里我写的最高约束是必须以行为保持为前提任何可能改变外部行为的重构必须显式标注风险。这一条压住了模型顺手改逻辑的老毛病。3. 实战三套可以直接抄作业的模板3.1 模板一高效代码审查模板人工校对版这套模板我用了最久效果最稳定先放成品角色你是一位拥有十年以上后端开发经验的资深代码审查专家长期从事大型分布式系统研发熟悉边界条件漏洞、并发竞争、幂等等高风险问题对代码可维护性有极高要求。 任务审查我提供的代码输出一份结构化审查报告。重点关注以下问题 1. 正确性死循环、空指针、越界、并发竞争、状态未回滚 2. 健壮性输入校验缺失、异常吞掉、超时未处理、重试策略缺失 3. 安全隐患注入、敏感信息硬编码、越权风险 4. 可维护性重复代码、过长函数、明显的架构问题 输入约定我将在审查代码标记之后提供代码。如果代码中有 TODO 或未完全实现的部分请在报告中单独说明。 约束与禁区 - 不要关注缩进、命名风格、注释数量等非功能性事项 - 不要为了凑数量上报问题没发现问题就明确说“未发现明显问题” - 问题必须能找到明确依据不输出猜测性结论 输出格式 ## 审查结论 两到三句话说明代码质量概况、是否可以合并入主干 ## 问题清单 | 严重等级 | 位置 | 问题描述 | 修复建议 | |---------|------|---------|---------| | 严重/一般/建议 | 文件:行号 | ... | ... | ## 改进建议 可选只写结构性建议不写琐碎改动设计这套模板时有一个细节值得说明约束与禁区里明确写了不要关注缩进、命名风格。为什么非要加这条因为在没有这条约束时模型经常把问题清单塞满变量名可读性差函数有点长建议拆分这类低价值建议真正致命的并发隐患反而被挤到后面去了。加这一条负面清单之后审查质量肉眼可见地提升。另一个容易忽略的细节是如果发现 TODO 或未完成的部分单独说明。这是我从一次事故里学到的。有次 Claude Code 审查一个含有 TODO 的半成品函数默认策略是基于推测补全逻辑并输出一条看起来合理的问题描述但那个推测和实际业务不符。让模板明确引导 AI 把TODO 与未完成作为独立关注项避免它把半成品当作完整的代码去评价。3.2 模板二行为保持重构模板老代码福音重构是所有 AI 编码工具最容易翻车的地方因为模型倾向于顺手优化。比如你让它重命名变量它把一处三元运算换成 if-else你让它拆分函数它顺手把默认入参值也改了。这套模板的核心目的就是锁死行为保持这条底线。角色你是一位精通重构的软件架构师熟悉 Martin Fowler 的重构方法论擅长在保持外部行为完全不变的前提下优化代码结构。你对“重构中改变行为”的情况高度警惕。 任务基于我提供的代码执行重构。允许的改动包括提取函数、更改变量名、简化条件表达式、拆分过长函数、调整类内部结构。禁止改变对外接口签名、默认行为、异常抛出顺序、边界处理逻辑。 输入约定如果代码量较大我会先提供目标文件路径你需要先阅读文件再操作如果代码量在 200 行以内我会直接在“重构代码”标记后粘贴。 约束与禁区 - 任何可能改变外部行为的调整必须单独标注风险不能混在普通重构里 - 不要引入新的依赖不要改动测试策略 - 重构必须保持单元测试可通过如果我没有提供测试你需要输出“未验证风险说明” 输出格式 ## 重构摘要 说明做了什么、保留了哪些行为保证 ## 改动清单 | 文件 | 改动类型 | 改动说明 | 行为影响 | |------|---------|---------|---------| ## 未验证风险说明 如果没有测试套件支撑明确写出哪些行为可能存在未验证风险我推荐这套模板给两个典型场景一是接手老项目时把那些几千行的面条式函数安全拆开便于后续维护二是做大规模重命名或者从回调改 Promise 时用。后者风险高行为不变的约束尤其重要。用这套模板最需要注意的是行为影响列。我要求模型在每一次改动后面都写清楚这对运行时行为有没有影响。一开始这会增加一点输出量但它会逼着 AI 在脑子里过一遍这次改动改没改语义实际减少的事故量远远超过那点 token 成本。3.3 模板三测试用例生成模板覆盖率增长利器很多团队的痛点不是不会写测试而是测试的覆盖路径太单一。让 Claude Code 生成单测时如果模板不到位它会生成一堆给定正常输入、期待正常输出的无用用例真正的边界条件全部错过。角色你是一位专注于单元测试的测试开发工程师擅长边界值分析、分支覆盖和故障注入。你熟悉多种语言的测试框架JUnit、pytest、Go testing 等习惯从“哪里可能出错”的角度设计用例。 任务为提供的函数或方法生成单元测试。请以“发现缺陷”为目标而不是“验证能跑通”。重点覆盖 - 边界值空值、零值、最小值、最大值、超长字符串、负值 - 异常路径异常抛出、错误返回、超时、内部失败 - 状态变化重复调用、并发调用、依赖状态变更 输入约定我会提供被测代码和语言/框架信息。如果被测函数依赖外部服务请优先使用依赖注入或 mock 策略并在测试中注明。 约束与禁区 - 不要生成只验证“正常路径”的测试用例 - 不要为生成简单的 getter/setter 创建测试 - 不要修改生产代码除非你明确说明必须拆分才能测试 - 每个测试用例必须写明验证意图 输出格式 ## 测试用例清单 | 用例名称 | 输入构造 | 预期行为 | 覆盖意图 | |---------|---------|---------|---------| ## 测试代码 用代码块输出完整测试文件 ## 风险与建议 指出被测代码中难以测试的设计并给出修改建议这套模板的三段式输出里我最看重覆盖意图那一列。让 AI 显式写出每个用例的意图实际上是在倒逼它思考这个用例到底覆盖了什么。如果没有这一列模型会生成大量看起来多、实则重复的用例加了这列之后覆盖率逻辑立刻清晰了。在我自己的工作流里这套模板和重构模板经常搭配使用重构前先生成测试重构后跑测试用同一套测试验证行为保持。两套模板结合起来AI 重构的安全性会高一个量级。4. 在 Claude Code 中落地使用模板的几种姿势4.1 姿势一通过 CLAUDE.md 全局注入基础约定CLAUDE.md 是 Claude Code 项目初始化时自动加载的全局上下文文件最适合放跨任务通用的约定而不是放具体模板。我在 CLAUDE.md 里通常放三类内容技术栈与目录结构说明、代码风格与质量红线、以及在哪些场景下推荐使用哪个模板的映射表。举个片段# 项目约定 ## 技术栈 后端使用 Go 1.22 PostgreSQL前端使用 React 18 TypeScript。 单元测试使用 Go testing testify覆盖率目标为 80%。 ## 质量红线 - 所有对外接口必须保持向后兼容除非有显式的 break-change 说明 - 禁止在生产代码中留下调试输出 - 数据库迁移必须提供回滚脚本 ## 模板映射 - 代码审查执行 claude -p $(cat templates/review.md) --file path - 重构执行 claude -p $(cat templates/refactor.md) --file path - 测试生成执行 claude -p $(cat templates/test-gen.md) --file path把模板映射表写进 CLAUDE.md 的意义在于它把用什么模板、怎么调用变成了一种团队共识别的同事拿到仓库后不需要问就知道该怎么让 AI 干活。这块建议所有做团队协作的人尽快用起来效果立竿见影。4.2 姿势二通过 -p 参数在命令行中直接调用Claude Code 支持-p参数直接传入提示词并返回结果这是我最常用的调用方式。配合模板文件我经常这样写claude -p $(cat templates/review.md)\n\n审查代码:\n$(cat src/main.go)这条命令有几个好处一是模板稳定不依赖我每次的临场发挥二是可以批量处理比如把多个文件名的循环丢进 shell 脚本里逐一审查三是输出是纯文本进 stdout可以接 jq、tee 等工具做后处理。为了让输出更可控我通常会再包一层脚本。比如我维护了一个review.sh它接受文件路径作为参数自动拼接模板和文件内容然后把输出格式化后追加到当天的审查日志里。这样一来每次审查都留痕后期回溯非常方便。#!/bin/bash # 用法: ./review.sh src/main.go FILE$1 PROMPT$(cat templates/review.md) echo -e $PROMPT\n\n审查代码:\n$(cat $FILE) | claude -p提示如果模板较长注意保持 prompt 中的输入约定与命令传参一致。我在模板里写的是审查代码标记之后提供代码所以命令里拼接的段落必须以审查代码:开头防止模型找不到输入。这个一致性设计直接决定了模板在命令行场景下能不能稳定工作。4.3 姿势三把模板组织成自己的提示词库目录随着模板越写越多我开始把它们当作真正的代码资产来管理。目录结构大概长这样claude-code-templates/ ├── README.md ├── CLAUDE.md.example ├── templates/ │ ├── review.md │ ├── refactor.md │ ├── test-gen.md │ ├── error-debug.md │ ├── commit-msg.md │ └── doc-gen.md ├── scripts/ │ ├── review.sh │ ├── refactor.sh │ └── test-gen.sh └── examples/ ├── review-output.md └── refactor-output.md这已经是我现在唯一在用的组织形式了。维护这个仓库的办法也很简单每次用模板发现结果不理想就打开对应的 md 文件增加一条约束每次想出新的任务场景就新建一个模板。核心原则是把模板当成迭代产品而不是一次性提示词。另外推荐在模板里写清楚版本号或最后修改日期。别笑这个细节救过我一次团队里有人改了一版审查模板把输出格式改成了 JSON结果下游脚本全部失效。因为没有版本标记排查了很久才发现是模板变了。加一个更新日期字段到模板头部以后这类问题三十秒就能定位。5. 我在模板实践中踩过的坑与沉淀的心得5.1 模板会过期要持续维护更新很多人以为模板写过一遍就完事了这是最大的误解。模型的版本迭代、项目技术栈的变化、甚至你自己对协作方式的偏好变化都会让模板逐渐失效。我曾经有一版模板在 Claude 3.5 上表现优异换到 3.7 之后就出现了严重的过度输出问题——每个问题都要长篇大论解释原理。后来补了一条约束每个问题的描述不超过三句话才把输出拉回正常。维护模板的频率不需要太高我现在的节奏是每周抽十分钟回顾一次看看最近几轮输出有没有跑偏如果跑偏了就找一条最共性的问题加进约束区。这种小步迭代比一次性追求完美有效得多。5.2 注意上下文窗口预算别被模板反噬模板是有上下文成本的。一个精心设计的模板可能就要 1200~2500 token如果代码文件比较大再加上历史对话很可能把上下文撑爆。代价是模型开始选择性失忆你早些时候提到的要求它会当成噪音忽略掉。我的经验是把模板压缩到 1500 token 以内并通过输入约定引导用户只贴必要代码而不是整个文件。举例来说审查模板里我写的是如果代码超过 500 行请描述核心逻辑并提供关键代码段不必贴完整文件。这样模板在自我保护同时也保护了上下文窗口。压缩模板还有一个技巧用表格代替散文。同样一段约束逻辑用散文写可能需要 400 token用表格写可能只要 120 token。模型的表格理解能力很强这一点我实测过多次放心用。5.3 从模板到工作流的进阶方向模板做到后面会自然长成一个更大的东西——工作流。比如我现在已经不完全是一个一个手动调claude -p了而是写了一组脚本把它们串成流水线改动代码 - 自动生成测试 - 运行测试 - 通过后进入代码审查 - 审查通过生成提交信息。每个环节都有一份模板在背后支撑AI 的输出从一个一个孤立的回应变成了一条稳定协作的生产线。如果你也想往这个方向走建议从最频繁的任务开始先给这个任务写好模板再写一个 shell 脚本把模板和文件拼起来最后再把多段脚本串起来。每走一步都能立刻感受到稳定性的提升。最后再分享一个小经验模板是写给别人用的但首先是写给你自己和未来的你看的。每次新建模板时不妨在开头写一句什么场景不要用这个模板比如测试生成模板里我会写如果被测代码是纯配置映射不需要单元测试。这能帮你在三个月后重新打开这个文件时快速判断它适不适用省下很多自我纠结的时间。claude-code-templates 这个项目走到现在带给我的最大变化其实不是输出质量的单次提升而是让我把 AI 协作从碰运气变成了有流程。希望上面这些模板和踩坑记录也能让你的 Claude Code 少一些薛定谔的发挥多一些稳定输出。
