1. 从每次手写提示词到沉淀模板库我为什么要折腾这件事先说个让我下定决心做 claude-code-templates 的真实场景。大约半年前我开始高频使用 Claude Code 处理日常编码任务。一开始还挺兴奋的——毕竟它能直接读整个代码库跑命令改文件比在网页对话框里一问一答痛快多了。但用着用着就发现一个问题同样性质的活儿我每次都得把提示词从头再敲一遍而且敲法还不一样。比如代码审查。有时候我说帮我看看这个文件有什么问题有时候我说请审查这段代码的边界条件有时候我顺手贴了一堆上下文却没说明审查的侧重点。结果是Claude Code 给我的反馈质量忽高忽低——要么泛泛而谈要么盯着鸡毛蒜皮不放真正想让它关注的性能瓶颈和并发安全问题反而被漏掉了。后来我意识到问题不在工具在于我没有把好用的交互方式固化下来。某个瞬间我给了它一段高质量的提示词它答得漂亮复盘时我把那段话存了下来下一次遇到类似任务我又能想起这段话来但记忆会衰减、变形。与其靠脑子记不如把那些试过之后发现真的有效的提示词统一收进一个目录按任务类型分类用固定的格式和参数接口。这就是我现在这套 claude-code-templates 的雏形。如果你也属于下面这几类人这文章可能对你有用刚开始用 Claude Code想知道除了随便聊之外怎么更稳定地拿到高质量输出已经用了一段时间但总感觉输出质量忽高忽低想找一种沉淀习惯在团队里推广 AI 编程工具想让大家用一致的方式调教同一个 AI。我在这篇文章里不会讲太多抽象概念主要是我自己的目录结构、几类模板的实际内容、把它们接入工作流的办法以及维护过程中踩过的坑。你可以直接照着抄也可以借这个思路搭一套属于你自己的模板库。简单说这就是一份实操记录不是教程式大全。2. 我的模板库长什么样目录结构、命名规则与版本管理这节先把整体框架讲清楚。我的模板库就跟项目放在一起是一个独立目录名字就叫claude-code-templates。为什么放在项目里而不是全局单独存一份因为模板只有贴近真实代码库才有意义。纯抽象的提示词像空中楼阁一旦结合项目上下文价值立刻翻倍。当然我的做法是通用性强的模板放全局和业务绑死的模板放项目这个后头细说。2.1 目录结构一览目前我的模板库目录长这样claude-code-templates/ ├── CLAUDE.md # 项目级规则文件Claude Code 启动时自动加载 ├── README.md # 模板库使用说明防止自己三个月后忘了怎么用 ├── templates/ │ ├── code-review.md # 代码审查最常用没有之一 │ ├── architecture-explain.md # 架构梳理理清陌生模块时用 │ ├── refactor-plan.md # 重构计划生成大改动前必用 │ ├── test-case-design.md # 测试用例设计侧重边界和异常 │ ├── dependency-audit.md # 依赖升级前的风险评估 │ ├── incident-triage.md # 线上问题快速排查 │ └── commit-message.md # 提交信息规范化团队协作时用 ├── commands/ │ ├── review.md # 定义斜杠命令 /review │ ├── arch.md # 定义斜杠命令 /arch │ ├── plan.md # 定义斜杠命令 /plan │ ├── test.md # 定义斜杠命令 /test │ └── audit.md # 定义斜杠命令 /audit └── workflows/ ├── feature-flow.md # 从需求到提测的完整工作流 ├── bugfix-flow.md # 修复问题的端到端流程 └── onboarding-flow.md # 新人快速熟悉项目的流程三个目录的定位不一样templates/放主模板是核心内容commands/是把模板变成斜杠命令的接线层workflows/是跨多个模板组合的更长流程。一开始我也没分这么细后来发现命令多了之后全挤在一个目录里很难维护才拆成这样的。2.2 命名与文件格式的约定给模板文件命名我有一条硬性要求文件名必须是动作对象的短语让别人以及一个月后的自己一看就明白这个模板是干嘛的。code-review.md比review.md更明确dependency-audit.md比check.md好一百倍。文件统一用 Markdown 格式因为 Claude Code 对 Markdown 的解析效果好而且我可以用###和列表把提示词的结构标清楚AI 更容易理解各部分作用。每个模板文件头部我还固定留了一块元信息区类似这样[tpl] name: code-review version: 2.3 last_updated: 2025-02-11 tags: [review, security, debug] scope_url: https://github.com/your/repo/tree/main/src这段元信息不会进入最终发给模型的提示词但它对我维护模板库帮助很大。版本号让我能追踪模板的演变tags 方便全文检索scope_url 告诉我看哪些目录是有意义的。有一回我升级了一个依赖旧模板里的路径全失效了正是靠 last_updated 字段定位到哪些模板需要改。2.3 版本管理模板也要 commit模板文件本身就是文本天然适合 Git 管理。我的模板库直接就是一个独立仓库每次我自己觉得这条提示词效果好就 commit 一次失败的就回滚。迭代久了我还能通过 git log 回看过往版本对比哪版提示词产出的结果更好。建议不要只用一个文件反复改保留完整历史因为你永远不知道下一个版本会不会更好用。除了 Git我还会给大版本打 tag例如v2.0代表命令机制的引入v3.0代表全面转向 workflow。这种版本标记在回看时能快速理解设计思路的更迭。3. 几类真正帮我扛过事儿的模板从代码审查到架构梳理这节进入正题把几类核心模板逐个展开。我不会把完整模板原文全贴出来那样太冗长而且很多内容跟项目绑死而是抽炼出它们的骨架和设计意图教你如何照着搭自己的版本。3.1 代码审查模板从随便看看到分点定级对这个模板我最初的启发来自一个糟糕的体验。某次提交前我随口说了一句帮我 review 一下这段代码结果 Claude Code 只反馈了两三句看起来不错注意一下命名之类的话毫无营养。后来我把审查要求做成模板把默认的整体看看改成了一套结构化指令。模板的核心骨架是这样的你现在是一名熟悉我代码库的资深代码审查者。请审查我传入的这段代码或 diff审查时严格遵循以下维度每个维度单独输出 1. 正确性是否存在明显的逻辑错误、边界条件遗漏、资源未释放问题 2. 安全性是否可能存在注入、越权、敏感信息泄露、不安全的反序列化 3. 并发与性能是否存在竞态、死锁、不必要的大对象持有、N1 查询 4. 可维护性命名是否准确抽象是否合理模块间耦合是否过高 5. 测试覆盖当前修改是否有对应的单元测试或集成测试 输出格式要求 - 每条问题以 [严重-高/中/低] 开头 - 严重为高的问题必须给出触发路径和具体修复建议 - 如果没有发现问题请明确输出该部分未发现明显问题不要用看起来不错敷衍。 额外约束当你不确定某段代码的意图时不要急着下结论先列出你的疑问再给出初步判断。你可能会问为什么非要把审查维度写成五条因为我发现 Claude Code 的能力很强但它的注意力需要引导。不限定维度它倾向于均匀分配注意力每个点都只摸一下限定之后它会更认真地逐个突破。配合[严重-高/中/低]这种标签也是在强迫它做出价值判断而不是胡子眉毛一把抓。有人可能会觉得输出格式要求太细像在考试。但审查这种任务结果是要给人看的。我拿着带有严重级别和触发路径的 feedback可以直接分派给同事或者自己按优先级修效率比看一大段散文式 review 高很多。3.2 架构梳理模板先理解再动手在接手一个老模块时我最大的痛点在于不敢动代码。谁都能改但改完了能不能跑谁也说不准。要真懂一个模块需要先梳理它的职责、依赖、数据流和环境假设。这个模板就是为这种场景设计的。它的核心提示词大致如下请扮演一名资深架构师帮助我理解代码库中 {module_path} 这个模块。不要修改任何代码只进行阅读与分析。按以下结构输出 1. 模块职责用 100 字以内的语言概括这个模块的职责以及它对外部系统的依赖。 2. 核心数据流描述数据从入口进入模块后经历的完整流转路径包括数据结构转换的关键节点。 3. 外部接口列出模块对外暴露的公开函数、类或 HTTP 接口标注调用方。 4. 隐藏假设找出代码中隐含的假设条件例如缓存依赖某个过期时间、线程模型是单线程等。 5. 潜在风险结合告警日志和 TODO/FIXME 注释列出你觉得风险最高的几个点。 完成后请先输出以上内容然后等我的下一步指令不要主动给出重构建议。注意最后那句不要主动给出重构建议——这很重要。AI 天生爱给建议但在我还没完全理解模块的时候它给的建议往往是基于不完整上下文的。只有先让它输出结构化的理解我确认无误之后才会进入下一步的修改指令。这个设计帮我把理解中和修改中两个阶段强行分开了。3.3 重构计划模板把大改动拆成可回滚的步骤大改动是最危险的。我以前试过让 Claude Code 直接重构某模块的某个逻辑结果它一口气改了十几个文件测试还跑挂了。后来我学乖了先用重构计划模板限定它。模板的逻辑是任何改动都必须三步走——先列影响面再拆阶段最后给验证清单。我需要你帮我设计一个重构计划目标{重构目标}。在给出计划之前先执行以下步骤 第一步影响面分析搜索并列出会受本次重构影响的所有文件和模块包括直接的调用方和被调用方。用表格输出每个文件的改动风险和原因。 第二步分阶段实施计划把重构拆成若干个可独立提交、可单独验证的阶段。每个阶段必须满足 - 改动不破坏现有测试 - 阶段结束时系统处于可运行状态 - 每个阶段都要有一个回滚方案。 第三步验证清单列出每个阶段完成后应该执行的验证动作包括运行哪些测试、检查哪些日志、人工确认哪些 UI 行为。 在输出重构计划之前先输出你找文件的过程让我确认没有遗漏。最后的输出找文件过程是个小窍门。它让 Claude Code 展示它读了哪些文件、如何定位相关代码。如果它漏了一个明显相关的模块我能当场打断纠正而不是等它给出计划后才发现。3.4 测试用例设计模板让 AI 补齐你想不到的边界写测试这件事AI 最擅长的是按照套路铺用例。但很多人让它写测试时它只会按着原始需求平庸地写几个正常路径的用例边界情况全靠你提示。我的模板专治这个问题。请基于以下需求描述设计测试用例{需求内容} 要求 1. 应用等价类划分和边界值分析法覆盖正常路径、边界路径和异常路径 2. 对每个用例给出测试名称、前置条件、输入、预期输出、覆盖的场景标签 3. 重点关注并发和分布式场景下的潜在竞态如果有必要设计一个能复现竞态的测试 4. 输出的测试用例需要直接可翻译成 pytest 或 JUnit 代码不要求写完整代码但每个用例要给出对应的断言思路。 在开始之前先花一点时间检查项目里是否已有同名测试文件如果有请在遵循现有风格的前提下补充而不是重头新建。加了这些硬约束后AI 生成的测试用例质量确实上了一个台阶。尤其是竞态设计这一条让 Claude Code 主动思考信号量、锁、超时这些我在提示词里没细说的东西能帮我补出不少真实项目里容易踩的坑。3.5 依赖升级与线上问题排查模板这部分挑两个场景简单说。依赖升级模板关注的是改动前风险可见——升什么、影响哪些接口、哪些间接依赖会变、回滚方案是什么。线上问题排查模板则侧重先彻底表达能力再动手改代码模板里强制 Claude Code 先列出它掌握的有限线索判断哪些信息缺失然后才给假设。这两个模板的具体内容我就不全贴了等你的场景出现了再展开讲。核心思路都一样给 AI 一个先想清楚再做的流程别让它直接冲到代码里改东西。4. 把这些模板接入日常工作流加载机制、上下文控制与团队协作模板写好了怎么让 Claude Code 在日常会话里真的用上说句实在话当初我把这些文件往仓库里一放就完事了结果第二天打开会话Claude Code 根本不认这些文件照样凭空聊。后来我才明白模板要起作用需要三层结构配合。4.1 第一层CLAUDE.md 项目规则文件CLAUDE.md 是 Claude Code 在项目会话启动时会自动加载的规则文件。它天然适合放两类东西一是项目的构建命令、测试命令、代码风格约定、目录结构说明等静态事实二是你需要的模板位于 claude-code-templates/templates 目录下这种导航信息。我推荐把 CLAUDE.md 作为整个模板体系的入口而不是把所有模板内容都塞进去。为什么CLAUDE.md 每次会话都会被加载到上下文中如果里面塞了 2000 行模板那每次对话烧掉的 token 都很可观而且大量无关内容会让模型的注意力分散。理想的 CLAUDE.md 应该短小精悍提示关键路径即可。比如我写的# Project Rules - 构建命令npm run build - 测试命令npm test - 新增功能请遵循 tests/ 下现有测试风格 # Template Navigation - 代码审查阅读 claude-code-templates/templates/code-review.md - 架构梳理阅读 claude-code-templates/templates/architecture-explain.md - 重构计划阅读 claude-code-templates/templates/refactor-plan.md这样 Claude Code 就知道有这么一套模板体系存在并且知道去哪找。当你在会话里说帮我做一次代码审查它会自动跳到那个文件去获取详细指令。如果模板没联网你直接说帮我审查它也会基于 CLAUDE.md 里的导航信息去找到对应模板。4.2 第二层斜杠命令把模板变成快捷键如果你觉得每次都要说请阅读 claude-code-templates/templates/code-review.md 这个模板再开始太啰嗦可以使用斜杠命令。Claude Code 支持自定义斜杠命令每个命令对应一个 md 文件放在commands/目录下。执行时输入/review scope它就会把命令文件里的内容作为上下文的一部分。我的commands/review.md大致长这样请对传入的代码范围执行一次全面代码审查审查指令请参考 claude-code-templates/templates/code-review.md。本次审查范围{传入参数}。如果参数为空请先列出当前变更涉及的文件列表再开始。注意这里的命令文件不是模板本体而是模板的转发器——它指明模板在哪里并把用户传入的范围参数传进去。这样命令文件短模板文件也不重复。斜杠命令的加载机制会在运行时把命令内容拼进上下文所以它们不需要像 CLAUDE.md 那样常驻。4.3 第三层控制先读后做的节奏模板接入工作流后最大的风险是它可能一步到位地改代码而不经过你的确认。所以几乎每一个模板里我都加了先输出计划/分析等待我的确认这类话。不是我不信任 Claude Code而是它的输出一旦落地到文件里形成事实后再修改的成本很高——哪怕只是多跑一遍重试也很消耗时间。具体到工作流我通常会在一个会话里这样用输入/arch path/to/module让 AI 输出架构梳理我确认梳理内容没错输入/plan 重构目标……拿到分阶段计划逐段推进每完成一个阶段跑一轮测试最后用/review审查整个 diff。这一套下来每一步都有明确的输入确认点任务步步可控。很多人觉得 AI 编程神秘其实它和带一个初级工程师一样——你给了流程它执行得就有板有眼你只给一句话它就开始自由发挥。4.4 团队协作让全组共享一版模板在团队里推广这套模板库时我发现一个很实际的问题大家用的 Claude Code 会话上下文、工作习惯都不一样模板如果写得太强硬同事反而抵触。我的做法是初期保留建议语气而不是强制。在模板开头注明这是一种推荐做法但你有权在需要时忽略或调整降低心理门槛。另外模板库的变更要走 PR 评审像代码一样。不是说你加了个模板就完事要让团队里有经验的工程师审一下提示词设计得好不好。好的提示词跟好的代码一样是有味道的——简洁、有约束、有明确输出物。经过几轮评审后模板库会慢慢变成团队的集体经验沉淀器。5. 模板库维护中的拦路虎僵化、冗余与过时我是怎么处理的模板用了大半年我踩过的坑不止一个。写五个模板容易让它们长期保持高价值难。这节说说几个典型的维护问题。5.1 模板僵化成套路模板最大的问题是做完了一件事就固化成仪式。比如我的代码审查模板一开始写得很啰嗦包含了很多示例条款。用了三个月后我发现 Claude Code 每次审查都按模板输出同样的结构和措辞哪怕有些审查根本不需要并发与性能这一维度。它不会主动判断并发维度是否适用而是机械地输出未发现明显并发问题。对此我的解法是给每个模板加上一个可选的裁剪指令在模板开头写清楚如果本次审查范围不涉及并发场景请明确说明并跳过并发维度不要输出无关内容。有时更直接的做法是给模板加一块[context]说明区告诉模型什么场景下应该用简约模式什么场景下用完整模式。模板不是流程刑具它是脚手架——该拆的时候要拆。5.2 模板内容逐渐冗余随着迭代模板会越改越长。新场景出现后我习惯往里加条款但很少删旧条款。半年后回看code-review.md已经膨胀到 200 行很多说法互相重叠。这样下来上下文消耗大模型的核心指令反而不清晰了。对付冗余我给自己定了一条规则模板改版时必须从这个模板最少需要哪些信息才能完成任务这个问题出发。具体办法是拿新版模板跑三次真实任务如果某条指令在这三次任务里都没有产生实质影响就删掉它。这个三次任务验证法虽然费点时间但能有效防止模板无脑膨胀。5.3 项目演进导致的过时模板里写死的路径、命令、环境假设都可能过时。项目从 Webpack 换成了 Vite从单体仓库拆成了多包仓库旧模板里那些针对单仓的假设就直接失效。我两处踩过坑。一次是依赖审计模板里写死了检查webpack.config.js的 external 配置后来项目不用 Webpack 了Claude Code 拿着这个模板检查时只会输出一句未找到该文件。另一次是重构计划模板里的验证命令从npm test变成pnpm -r test忘了同步到 CLAUDE.md结果多次跑错命令。这部分的补救办法就是在模板元信息里加适用场景和影响路径字段模板更新时对相关路径做一次全局检查。项目结构变更大的时候我会专门开一个会话让 Claude Code 对照所有模板里的路径假设检查是否仍有对应文件存在。这个流程不是一次性的最好每两个月执行一次。5.4 别把模板当成咒语最后也是最重要的一点模板是高效的工具但它不是银弹。我在维护这套 claude-code-templates 的过程中最大的体会是AI 工具的可塑性很强但前提是使用者有一套清晰的目标和边界。模板提供的只是把任务描述清楚的一种手段真正高风险、高价值的判断仍然要由人来把关。所以我的建议是模板里的每条指令都应当能回答我为什么要这样要求它这个问题。如果连自己都不知道这条指令的作用那这条指令可以考虑删了。所有有效的模板本质都是把你对某类任务的思考固化下来。这套思路不只适用于 Claude Code未来换成任何 AI 编程工具你都能快速迁移过去。最后再分享一个小技巧每次用模板跑完一个任务我会花几秒钟在文件末尾追加一行本次执行结果的备注例如发现 3 个高严重问题全部已修复或者架构梳理结果与预期一致未执行重构。半年下来再看这些备注你能很清楚地知道这个模板多久没用了、是否还需要继续保留。这种小习惯比任何宏大的整理都管用。