先交代一下背景我平时重度依赖 claude-code 做日常开发短到改一个函数签名长到从零搭一个服务都习惯丢给命令行里的这个 AI 助手去处理。用久了之后发现一个特别尴尬的问题每天有大量指令是重复的项目初始化、代码审查、重构、写测试、整理提交信息翻来覆去就是那几套说法。刚开始我还能靠肌肉记忆临场敲但一旦换项目、换机器或者隔几天不用整个提示词的质量就飘了。所以我专门整理了一个叫 claude-code-templates 的仓库把所有高频场景沉淀成可复用的模板文件配合检索脚本按需加载效果比我预想中好得多。这篇内容就是把我做这个模板库的完整思路、目录设计、模板写法、踩坑记录一次性倒出来给同样在折腾 AI 辅助开发流程的朋友做一个参考。1. 项目整体思路与其调模型不如先管好输入我最早以为提升 claude-code 输出质量的关键是“写出更妙的提示词”后来发现单条提示词再妙也只是局部最优。真正让产出稳定的是把提示词当成产品来维护分门别类、带版本、可检索、能复用。claude-code-templates 这个项目本质上不是“写几个模板文件”而是围绕 AI 编程助手建立一套输入侧的基础设施。1.1 高频场景识别是第一步动手之前我先翻了最近两个月在终端里的历史操作把使用 claude-code 的会话记录全部过了一遍按任务类型做了粗略归类。列出来的高频场景大概有六类从零初始化项目、给既有代码做审查、重构某个模块、补齐单元测试、分析报错日志、整理 git 提交信息。这六类占掉了八成以上的调用次数而且每一类的输入结构都高度相似项目背景、目标、约束条件、期望输出格式。拿“代码审查”来说不同会话里我反复输入的其实是同一套东西先告诉它项目用的语言和框架再说明这次改动涉及哪些文件然后要求它按正确性、性能、可维护性三个维度给意见。既然这套话术每次都差不多为什么不把它固化成模板模板里把变量部分空出来用的时候填进去就行这样既能保证每次都覆盖到关键维度又不会因为临场发挥漏掉某个环节。1.2 模板库要解决的三个具体问题设计 claude-code-templates 的时候我明确给自己列了三个目标。第一是降低每次会话的“启动成本”以前我光是描述背景和约束就要写两百字现在用模板一次粘贴就能把上下文铺好。第二是提升输出的一致性同样的任务用同一套指令框架模型输出结果的风格和粒度会比较稳定不会今天给一段代码、明天给一篇小作文。第三是沉淀个人经验模板里的每一句话几乎都是从过往实践里筛出来的凡是导致过坏结果的指令表述都被改写过这个仓库其实是拿时间和教训堆出来的。这三个目标对应了三种具体设计决策目录结构按场景划分而不是按项目划分模板内容用占位符代替硬编码信息加载方式做成命令行工具而不是复制粘贴。后面我会逐个展开说明但最核心的一点是模板一定要比你的即时输入更认真。你随手写的提示词可能只有三四行模板里我通常写到五六十行包含背景说明、执行步骤、输出格式、反例提示甚至还会塞一两个 few-shot 示例。这不是废话堆砌而是在给模型搭建足够明确的解题脚手架。1.3 为什么用纯文件而不是靠工具链市面上有专门的 prompt 管理工具甚至 claude-code 自身也支持在项目里配置命令。我最终还是选择了最朴素的方案一个普通 git 仓库里面全是 markdown 文件外加一个几十行的小脚本做搜索和复制。原因很简单纯文件零依赖随便换一台机器都能用也不存在工具版本升级导致配置失效的问题。而且 markdown 本身就是 claude-code 最舒服的输入格式模板可以直接被读取、被粘贴甚至被再次编辑。仓库用 git 管理天然带版本历史和多人协作能力我可以在分支上迭代模板确认有效之后再合进主分支。注意模板文件最好不要搞成 JSON 或 YAML 这种结构化格式。虽然解析起来方便但写模板的时候会被语法限制框住可读性也差。Markdown 才是 prompt 的最佳载体模型读起来顺人维护起来也顺。2. 模板库的目录结构与设计准则做这个仓库的第二天我就领悟了一件事模板的目录结构决定了你愿不愿意持续用下去。如果找一个模板要翻三层目录而且文件名长得毫无规律那热情很快就会被消耗光。我现在的目录设计原则是“场景优先、入口收敛、文件名自解释”。2.1 按任务场景组织目录仓库根的 templates 目录下我按场景建了这些文件夹project-init、code-review、refactor、test-writing、debugging、git-workflow。每个文件夹里放两到三类文件一两个核心模板、若干配套片段、一个 README 说明这个场景下什么时候该用哪个模板。以 code-review 为例里面有三个文件review-general.md 是通用代码审查模板review-security.md 是针对安全和权限问题的专用模板review-perf.md 是性能专项审查模板。使用频率决定了颗粒度通用的放一个专项的按需单独建。如果你把每个小场景都单独建一个模板比如“审查函数命名”“审查数据库索引”最后会发现模板之间大量重复维护成本直线上升。折中的做法是通用模板覆盖常规情况专项模板只覆盖那些你真的经常遇到且通用模板覆盖不够的场景。2.2 模板文件的通用骨架我写每个模板都会遵循一个固定的五段式骨架角色定义、任务背景、执行步骤、输出格式、质量要求。角色定义告诉 claude-code 应该以什么身份来处理问题任务背景里填项目技术栈、代码路径、相关上下文执行步骤把一个大任务分解成三到五个子任务输出格式明确结果的组织方式质量要求划出底线比如“不要修改非相关文件”“所有建议必须附带代码示例”等。下面是一个典型的模板骨架示例# 角色 你是一名资深的 Python 后端工程师擅长代码审查。 # 任务背景 项目{project_name} 技术栈{tech_stack} 代码路径{code_path} 本次变更目标{change_goal} # 执行步骤 1. 阅读 {code_path} 下的 diff梳理本次变更涉及的核心逻辑 2. 检查正确性是否存在边界条件漏处理、异常未捕获、并发安全问题 3. 检查性能是否存在循环内重复计算、不必要的数据拷贝、N1 查询 4. 输出审查结论 # 输出格式 按问题严重程度分组致命问题/建议改进/风格问题 每个问题需包含文件:行号、问题描述、修复建议、示例代码 # 质量要求 - 只审查本次 diff 涉及的内容不要扩大审查范围 - 每个问题必须给出可执行的修复代码 - 没有问题的维度明确写未发现问题这个骨架之所以管用是因为它把模型的思考过程从“自由发挥”压缩成了“填空作答”。逐段提供了约束模型不需要在每次会话里猜测你想让它怎么工作。2.3 模板里的变量策略模板里一定会有需要每次填写的变量比如项目名、代码路径、目标等。我统一用{变量名}这种占位符格式不用双大括号也不用变量名。原因很实际{}在 markdown 里不太常见不容易和正文内容冲突而且在某些场景下会被解析成 HTML 标签容易引起混乱。变量命名也有一些小讲究。尽量用“语义单位”的方式例如{code_path}而不是{a}变量在模板中出现的次数越多越要靠前定义如果某个变量是可选的要在模板开头注明“如果不知道可以留空”。最重要的是不要让变量承担复杂的逻辑。模板不是编程语言如果你发现自己在一个位置写了类似“如果 A 就输出 B 否则输出 C”的伪代码说明这个模板拆得还不够细。2.4 每个模板必须附带元信息区我在每个模板文件的开头会加一小段 YAML 风格的元信息区用注释或者专门的标记包裹里面记录模板用途、适用条件、最后更新时间、依赖的上下文。这样做有两个好处。一是用 rg 搜索的时候可以快速过滤“我要找一个关于性能审查的模板”直接搜元信息里的关键字就能命中。二是模板进入维护期之后你可以通过元信息里的更新时间快速判断哪些模板已经过期需要根据新的工程项目实践做调整。元信息区写完后建议下面空一行再进入正文。很多解析工具会按“前置元信息正文”的结构去读强行保持格式统一能省掉很多后续处理上的麻烦。3. 核心场景的模板实现细节分类和骨架只是脚手架真正拉开使用体验差距的是模板里的措辞、步骤编排和示例选择。这一部分我挑几个最常用的场景把模板的关键细节拆开讲重点说清楚每一句话背后的意图。3.1 项目初始化模板让模型先问再做项目初始化是最容易翻车的场景。以前我直接丢一句“帮我初始化一个 FastAPI 项目”模型通常会咔咔生成一堆文件结构但往往不是我要的版本依赖没锁版本、目录结构不符合项目约定、没有配 linter。后来我把 project-init 模板设计成“先提问再动手”的模式。模板开头明确要求如果项目背景信息中缺少关键字段比如 Python 版本、包管理工具、是否需要 Docker必须先列出待确认项等用户明确回复之后再生成完整内容。这一步极其关键它把模型从“闷头生成”变成“交互式确认”。代价是多了一轮对话但换来的是初始化结果不再需要大幅返工。模板里还规定了几条硬性生成规范所有依赖必须标注具体版本号而不是 latest目录结构必须包含 tests 和 docs 两个目录初始化完成后必须附带一份简短的 README 说明如何启动项目。这些约束来自真实踩坑——不锁版本的依赖会在半个月后悄悄升级导致项目跑不起来没有 tests 目录的项目后面再补测试的意愿会断崖式下降。模板存在的意义大概就是这种“把历史教训固化下来”的感觉。3.2 代码审查模板限定审查范围是第一优先级代码审查模板里最重要的一句话是“只审查本次 diff 涉及的内容不要扩大审查范围”。这不是为了让模型偷懒而是因为 claude-code 在读取代码时很容易顺着代码逻辑“越看越远”最后给你一份覆盖整个代码库的报告里面真正和本次改动相关的可能只占三分之一。限定范围之后输出质量显著提升报告变短了但每条问题都直接落在点子上。审查维度的编排顺序也有讲究。我按“正确性 → 性能 → 可维护性 → 风格”的顺序排列而不是按照代码文件顺序排列。这样做的原因是正确性问题一旦发现性能优化建议很可能就不再成立风格问题更是排在最后。让模型按照优先级逐层检查避免它在一个风格问题上纠结半天却漏掉了真正的逻辑缺陷。3.3 重构模板强制带上测试保护网重构是 claude-code 翻车率最高的场景因为模型往往会“重写”而不是“重构”。重写意味着推翻旧实现引入全新的设计这会让 diff 变得巨大风险难以控制。重构模板的第一步就写死了一条规则先保持外部行为不变只修改内部实现所有改动必须保证原有测试通过。为了让这条规则真正落地模板要求在执行重构之前先让模型检查当前项目是否有足够的测试覆盖。如果没有它会建议先补充关键测试再开始重构。这等于在重构流程里套了一层安全网。以前我一冲动就把重构任务丢给 claude-code结果是功能跑通了但老的边界行为全变了测试红了一大片。现在模板把“先看测试、补充测试、再重构”写进了流程类似的惨剧很少再发生。重构模板里还包含一个非常实用的输出要求每次移动代码或修改逻辑之后必须写一段两行左右的变更说明说明这次改动的动机和预期影响。这个要求让模型的每一步都有迹可循如果改错了我能从变更说明里快速定位到是哪一步引入的问题。3.4 测试生成模板用少示例带动多场景写测试模板我踩过比较深的坑是“示例太多导致模板过长”。一开始我塞了五个不同的测试场景作为 few-shot 示例结果模板文件膨胀到两百多行模型读起来费劲上下文窗口也被挤占。后来我把示例压缩到两个一个是最典型的“正常路径”示例一个是“边界条件”示例。两个示例足以让模型理解我想要的测试风格和断言粒度但不会喧宾夺主。测试模板里的风格约束写得非常具体。比如“测试函数命名必须用test_受测函数名_场景的格式”“每个测试用例只验证一个行为”“对于时间相关的逻辑使用依赖注入而不是 sleep 等待”。这些约束写多了以后模型生成出来的测试代码几乎可以直接进 CI不需要我再手工调整风格节省下来的时间非常可观。3.5 调试模板让模型先复述再定位调试场景的特殊之处在于用户给到的报错信息往往只有一小段日志但真正的病灶可能在日志之外很远的代码里。调试模板的思路是先让模型“复述对问题的理解”然后列出可能的原因清单再逐个排查。这个“先复述再定位”的流程防止了模型拿着半截日志就急着给结论。很多时候模型输出的第一版假设是错的但它会在复述过程中暴露自己的理解偏差这时候我能及时纠正方向而不是等它改完代码才发现理解错了。调试模板还会强制模型区分“直接报错原因”和“根因”。日志上显示的往往只是现象真正的原因可能在调用链的上游或者配置项里。模板要求模型把这两个层级分开写先分析直接原因再追问根因逐层下探。实测这个写法对于排查异步任务超时、内存泄漏这类棘手问题的帮助特别大。4. 工作流接入怎么在日常会话里用起来模板文件建得再漂亮如果接入日常使用的方式很别扭最后还是会被闲置。这一部分讲讲我怎么组织实际工作流以及检索和加载脚本的核心逻辑。4.1 用 fzf 做模板选择器我的做法是写了一个叫tpl的脚本核心功能是调用rg在 templates 目录里搜索关键词把结果交给fzf做交互式选择选中后直接把文件内容读进剪贴板。这个流程的体验非常顺滑按一下快捷键唤起终端输入“review”回车所有和审查相关的模板文件列出来选中一个就自动复制到剪贴板然后回到 claude-code 的会话里粘贴即可。脚本的核心部分大概长这样#!/usr/bin/env bash # 用法: tpl [关键词] # 示例: tpl review, tpl init, tpl test SEARCH_DIR$HOME/.claude-templates/templates KEYWORD${1:-} if [[ -n $KEYWORD ]]; then # 有关键词时直接检索文件名和内容中的匹配项 SELECTED$( rg -l --ignore-case $KEYWORD $SEARCH_DIR \ | fzf --preview head -40 {} ) else # 没有关键词时列出所有模板文件 SELECTED$(find $SEARCH_DIR -name *.md | fzf --preview head -40 {}) fi if [[ -n $SELECTED ]]; then cat $SELECTED | pbcopy # macOS 用 pbcopyLinux 可用 xclip echo 已加载: $(basename $SELECTED) fi这个脚本有一个我觉得很关键的细节预览窗口只显示文件的前 40 行。因为模板文件的元信息区就在开头前 40 行足够让我快速判断这个模板是不是当前场景需要的又不会把整个文件刷屏。选完模板之后不一定立即粘贴可能我还需要在里面改几个变量所以脚本只是切到剪贴板不做别的。4.2 项目级模板与全局模板分开管理每个人大概都会有“全局通用”和“本项目专用”两类模板。全局模板放在~/.claude-templates/templates目录下适用于所有项目比如代码审查、日志分析、提交信息生成。项目专用模板放进当前仓库的.claude/templates目录里记录的是这个项目特有的约定、代码风格、部署流程。检索脚本默认会先搜项目目录再回溯到全局目录这样同名的项目级模板会覆盖全局模板实现分层管理。这个分层设计非常实用。比如我在 A 项目里约定用 pytest 和异步风格的测试在 B 项目里却用 unittest 和同步风格的测试两个项目各自放一份测试模板就可以互相不干扰。全局模板用来维持通用能力项目模板用来适配具体项目的特殊性互不污染。4.3 变量替换我用最简单的 sed有些情况下我不想复制模板后手工替换变量而是希望在脚本里就把{project_name}这种占位符直接换掉。我最初的版本写了一个复杂的 Python 脚本去做替换后来发现大部分时候没必要。现在只在极少需要批量替换的场景下用 sed例如# 复制并替换模板中的变量 cat templates/code-review/review-general.md \ | sed s/{project_name}/order-service/g \ | sed s/{code_path}/app\/services\/order.py/g \ | pbcopy这种做法在变量少的时候效率最高但变量超过四五个就很容易出错尤其是项目名和路径里本身包含特殊字符的时候。所以我现在主推的方案仍然是“复制后手动替换”模板原样进入会话然后让 claude-code 扮演“变量填充者”你只要在会话里告诉它相关上下文它自己会把模板里的占位符替换成实际值。反而比 sed 那一套少出错而且模型在替换过程中还能理解这些变量之间的语义关联。4.4 日常使用流程复盘我一天的使用流程大概是这样的早上到工位先跑一遍tpl扫一眼有哪些模板可以复用开始新任务时先选一个模板铺底再在里面补充本次项目的个性化信息任务中途如果发现模型给出的结果不符合预期我会检查是模板指令没被遵循还是变量给得不全然后针对性修正。一天工作结束后如果某个任务场景已经出现了两次且现有模板无法很好覆盖我会当天就新建一个模板并 commit。这套流程跑顺之后一个特别明显的变化是和 claude-code 的交互从“对话式试探”变成了“按单执行”。我给它模板它按照模板的步骤走中间产出的偏差明显变少。虽然牺牲了一点灵活性但对日常工作来说稳定可预期的输出远重要于偶尔灵光一现的效果。5. 常见问题与排查技巧实录做模板库不是一锤子买卖维护过程中会碰到各种奇奇怪怪的问题。这里记录几个真实踩过的坑以及我摸索出来的排查方法。5.1 模板内容生效打折指令被淹没在了上下文里最经典的问题是模板明明写得很好但 claude-code 跑出来的结果却完全没有遵循模板里的输出格式。后来我复盘发现问题往往出在“模板被夹在了一大段对话中间”。如果用户先和模型聊了几轮又突然丢进去一份模板模型会把模板当成新的对话内容的一部分参考权重自然很低。解决办法有两个。第一模板必须在会话开头就加载让模板成为第一轮用户输入这样它在语境中占据主导地位。第二在模板结尾加一句“请严格遵循以上指令如果信息不足请直接提问”用明确的语言提醒模型这是一份指令文件而不是参考材料。如果模板已经在中途加载我会在模板前额外写一句“这是一份新的任务指令请忽略之前的任务设定严格按照以下模板执行”效果立竿见影。5.2 变量占位符残留模型没有完成替换有时候模型输出内容里会残留{project_name}这样的占位符说明它没有把模板里的变量当作待填项。这通常是模板里变量命名太抽象导致的。第一次出现这个情况时我把变量从{p}改成了{project_name}残留率立刻降低了一大截。后来又发现如果变量在模板里只出现一次且放在了不起眼的位置模型特别容易漏掉。所以我调整了模板结构所有变量先集中列在“任务背景”区域正文中引用变量时尽量用醒目措辞。万一残留还是发生我会在会话里追加一句“把上面模板中的 {project_name} 替换为 order-service然后按替换后的内容执行”。让模型先替换再行动而不是自己去脑补。这个“显式替换指令”几乎能百分百解决占位符残留问题。5.3 模板之间内容打架全局模板和项目模板的优先级项目模板和全局模板里的指令如果互相矛盾claude-code 有时会选择服从后者导致执行结果不一致。比如全局模板说测试要用 pytest项目模板说用 unittest模型在这个矛盾面前的表现经常是两头兼顾生成一份不伦不类的测试文件。排查办法是在模板元信息里明确标注“本模板覆盖同类全局模板”并在项目 README 里说明哪些全局模板不适用。加载时我还会检查是否有同名的项目级模板存在过一次避免依赖默认的覆盖逻辑。5.4 调试模板的方法用一个测试项目来验证排查“模板为什么没生效”这类问题时我习惯准备一个专门的空测试项目里面只放一个最简单的函数。然后每次修改模板我都会在这个测试项目里跑一遍完整流程观察输出是否严格遵循模板要求。这个测试项目只改动一个变量比如函数名来模拟真实场景。花十分钟做一个最小复现比直接在生产项目里试错要快得多而且不会污染真实项目的上下文。另一个调试思路是“把模板本身作为审查对象”。如果模板生成的输出总是不符合预期我会把模板文件贴给 claude-code请它从第三方角度审视模板里是否存在模糊表述、过强约束或相互矛盾的指令。这种“让模型审查模板”的做法往往能发现我自己没注意到的问题比如某个表述在中文语境下有多重解读或者说约束条件超过了模型的能力边界。5.5 维护节奏什么时候该新增模板模板不是越多越好而是要维持“能用一条模板覆盖的场景不拆成两条”的精简原则。我给自己定了一个规则同一个场景在两周内出现超过三次迫使额外手动补充说明才考虑新建模板。如果只是偶尔一次就在旧模板里加一句覆盖那类变化的措辞。这样能防止模板库膨胀到一个难以维护的规模。目前模板总数控制在三十个左右每个都已经经过至少三次真实任务验证淘汰率和新增率都不高。6. 长期维护的体会与后续可以做的事最后分享几个我持续维护 claude-code-templates 项目过程中的体会。模板库的价值不在于数量而在于每一次模板更新是不是沉淀了新的、经过验证的经验。所以我会刻意避免一次性写大量模板而是坚持在真实任务中发现问题之后再去更新模板。有一次我为了“感觉上更完善”一口气写了十几个模板后来发现其中至少四个从来没有被真正使用过因为对应的场景根本不常出现它们只是占用了我的维护精力。后来我狠心删掉了那几个模板自责了很久但也把“从真实需求出发”刻进了这个项目的维护原则里。这个项目后续还可以做几件事。目前模板里以源码审查和项目初始化为主调试场景的模板还比较粗放可以结合更多真实故障案例去打磨“故障树式”的排查流程。另外模板文件目前还是靠 git 仓库分发之后可以写一个更完善的管理脚本支持通过命令行直接安装模板到项目目录、检查模板与当前项目技术栈的匹配度甚至可以把团队内不同成员维护的模板做合并和冲突检测。这些扩展方向都建立在已经稳定沉淀的模板体系之上属于锦上添花。说到底claude-code-templates 这套东西的核心价值就是把和 AI 编程助手协作时的“临时发挥”变成了“工程实践”。每次新任务不再从空白对话开始而是从一份精心设计过的指令文件出发输出质量自然更稳。如果你也在天天用 AI 辅助写代码真心建议动手整理一套自己的模板哪怕从两三个最常用场景开始用起来之后再慢慢迭代。这个过程本身也会让你对自己平时的工作方式多一层清晰的审视。写完这篇内容我倒想起来一件事claude-code-templates 里我最常用到的其实不是写代码模板而是那个只有十五行的 git 提交信息模板。后者的使用频率远远高于我之前预期。这也是模板设计的一个有意思的规律——真正高频的场景往往看起来都非常简单而越是简单的高频场景越值得用模板去固定住它的输出质量。