做过一阵子 Claude Code 之后我最大的感慨不是模型能力不够而是同样一句话换个项目、换个时机、换个人来敲出来的结果能差出十万八千里。后来我认真梳理了一轮自己的 prompt 习惯把每次都要手写的那些“开场白”“约束条件”“输出格式”全部抽出来整理成了可复用的模板库。这个库我起名就叫claude-code-templates原本只是为了自己少打几行字结果变成了整个团队协作时的统一入口。这篇文章不聊宏大理论就从我实际维护这个模板库的经历出发讲讲 prompt 为什么要模板化、模板库怎么组织、模板内部怎么写才算数、以及日常使用时最容易翻车的几个地方。如果你也用 Claude Code 处理日常开发、文档梳理或方案设计这篇应该能帮你少走很多弯路。1. 给 Claude Code 做“乐高积木”为什么 prompt 必须模板化先说一个很反直觉的结论越是强调“自然对话”的 AI 工具就越需要格式化的输入。Claude Code 的优势在于它能在终端里替你跑命令、读文件、改代码但它本质上是“理解你的意图 执行具体操作”。如果你的意图表达得模棱两可它就只能在模糊地带自由发挥。自由发挥的产物听起来漂亮用起来难受。1.1 不固定 prompt 的三个代价随手写 prompt 最大的问题是不可复现。你今天让 Claude Code 帮你重构一个函数它写得不错明天想让它在另一个项目里做同样的事你把记忆里的那段话敲出来它却理解歪了。问题往往出在表述细节上——你少交代了一句“保持对外接口不变”它就大刀阔斧把函数签名改了。第二个代价是上下文浪费。Claude Code 的上下文窗口再大也是有限的每次对话都要先解释项目背景、技术栈、约束条件。不做模板就等于每开一个新会话都把相同的信息反复投喂一遍。投喂得越多真正用于处理任务的额度就越少。第三个代价是风格漂移。同一个功能今天让它“简洁实现”明天让它“健壮优先”后天又“考虑性能优化”没有约定俗成的基线代码风格完全看它心情。等到 review 的时候你就知道统一 prompt 模板对代码风格的管理意义了。1.2 模板化之后发生了什么我把模板库建起来之后最直观的变化是开会前不需要再做“人工翻译”。任何人想启动一个任务先到 templates 目录下挑一个骨架填上自己的项目上下文再用 Claude Code 跑起来输出质量基本能落在一个稳定的区间里。打个比方就像是给一个写文章特别快但不稳定的笔者发了一张标准稿纸标题位置、正文结构、重点标粗区域都画好了他能发挥的上下限被拉近了。你不需要他每次重新发明文章框架只需要他把观点说清楚。所以prompt 模板的本质不是限制 AI而是把人的经验沉淀成工具能消费的固定格式。你的历史踩坑记录、团队编码规范、项目目录结构都通过模板一次性注入到对话里让 Claude Code 从“一个聪明但陌生的协作者”变成“懂你项目规矩的固定成员”。2. 不只是一个文件夹那么简单的库结构设计很多人一开始会把模板库做成“一堆 .md 文件堆在目录里”然后越堆越多到后面连自己都分不清哪个是哪个更别说维护。我重新设计 claude-code-templates 的第一件事就是把“仓库根目录”变成一个清晰的工作台。2.1 目录组织按任务类型分主仓按场景分支我的模板库长这样claude-code-templates/ ├── README.md ├── templates/ │ ├── dev/ │ │ ├── refactor.md │ │ ├── feature.md │ │ ├── bugfix.md │ │ └── review.md │ ├── docs/ │ │ ├── api-reference.md │ │ ├── adr.md │ │ └── changelog.md │ ├── research/ │ │ ├── db-schema-design.md │ │ ├── architecture-plan.md │ │ └── tech-selection.md │ └── generic/ │ ├── quick-question.md │ ├── explain-code.md │ └── write-tests.md ├── snippets/ │ ├── coding-style.md │ ├── stack-context.md │ └── commit-format.md ├── workflows/ │ └── session-start.md └── scripts/ ├── render_template.py └── list_templates.sh这里有个关键决定不把所有内容都塞进模板文件。大模板负责骨架小片段负责肉。templates目录放的是“结构性模板”它们解决的是“一件事从哪开始、包含哪些必要组成部分”的问题。比如feature.md不会关心你用 React 还是 Vue它只关心一个功能需求描述是否覆盖了用户故事、验收标准、影响范围、测试策略。snippets目录放的是“项目特定信息片段”像技术栈描述、代码规范摘要、commit 格式这些是和某个项目强相关的。它们被设计成可以被插入到任意模板里的独立单元。workflows目录则负责“会话起点”比如你每次启动 Claude Code 时先喂一份项目地图快速建立上下文。这样分工是为了避免一个经典问题模板里写满了项目信息换个项目就用不了模板里只写骨架又起不到约束作用。拆分以后通用骨架和项目信息就像乐高积木一样自由拼装。2.2 给模板文件加 Front Matter让模板可以被检索纯 Markdown 文件有个弱点——没法结构化描述自己。你只能靠文件名猜内容时间久了根本记不清refactor.md和optimize.md的区别。我在每个模板头部加了一段 YAML 格式的 Front Matter类似博客系统里常见的元信息写法--- name: feature version: 2.1.0 category: dev description: 用于新功能设计、开发、验收全流程引导 variables: - feature_name - target_dir - user_story related: - snippets/stack-context.md - snippets/coding-style.md ---这些小字段有什么用脱离场景看似乎没什么大用但一旦你的模板库超过二十个文件它们就变成了检索和管理的基础name给每个模板一个唯一 ID命令和脚本都靠它引用variables声明了这个模板需要哪些动态变量渲染脚本可以据此做校验漏填自动提示related指明当前模板要搭配哪些片段使用相当于模板之间的引用关系。2.3 版本管理要跟代码一样严格我见过很多项目模板的维护方式是“就地修改”今天觉得这个措辞不对直接改了明天又把改掉的改回来某次改动让所有使用者的输出风格都变了却没人说得清是哪天变的。模板一旦被团队使用就应该像代码一样走版本控制并且遵守语义化版本规则版本类型触发条件示例大版本结构性变化所有使用者的输出都会受影响3.0.0 重写了输出格式章节中版本新增可选章节不改变默认行为2.2.0 新增“性能约束”选项小版本微调措辞不改变结构2.0.1 修正了一段表述模糊的约束预发布内部测试未对外推广2.1.0-rc.1版本记录不只是写在 Front Matter 里还要维护一份CHANGELOG.md说明每个版本改了哪些内容、动用了哪些变量。这样当一个人抱怨“这个模板最近效果变差了”你可以先翻版本记录而不是靠猜。3. 模板的“四层骨架”角色、上下文、任务、约束这一节是精华我花了最多时间打磨的地方。一个有效的 Claude Code 模板内部结构必须要有四个层次缺一个输出质量就会出现肉眼可见的下降。3.1 第一层角色与行为准则角色设定不是写上“你是一个高级前端工程师”就结束那太敷衍了。真正有用的角色设定必须包含行为边界和工作习惯。看一段我refactor.md里的写法## Role 你是一位资深的代码重构专家习惯于在不改变外部行为的前提下改善代码内部结构。 你在收到重构任务时会先识别代码的输入输出和公共 API再开始动手。 ## 行为准则 - 优先理解现状禁止未经确认就大规模重写。 - 必须保持对外接口和函数签名不变除非任务中明确说明允许修改。 - 每一步重构后都要确认现有测试能够通过。 - 遇到不确定的地方先列出问题清单不要猜测。注意到差异了吗前半部分是“身份身份”后半部分是“行为准则”。行为准则实质上是对 AI 的约束条件。没有这些约束它当然也会重构但它会按它自己的偏好重构而不是按你的项目习惯。我的经验是行为准则的数量控制在 5 条以内。超过 5 条Claude Code 的执行效果会边际递减它会在一条又一条的规则里迷失优先级。这就像给新员工列了一百条注意事项结果他每条都记了每条都没做到位。3.2 第二层项目上下文注入第二层的内容不是让你在模板里写死“我的项目是 xx”而是通过变量和片段机制动态注入当前项目的具体信息。以feature.md为例模板中间有一个标记## Context 下面的内容由项目特定片段提供请把它们作为理解本任务的基础 {{ stack_context }} {{ coding_style }} 当前工作目录{{ project_root }} 项目中的关键目录{{ key_dirs }}这段内容在渲染时会被替换成具体的项目信息。比如stack_context.md可能是技术栈概览 - 前端Vue 3 TypeScript Vite - 后端Node.js 20 Express - 数据库PostgreSQL 15通过 Drizzle ORM 访问 - 测试Vitest Testing Library - 项目结构src/{components,pages,stores,utils,server}测试文件与源码存放在一起这样做的目的是让模板在不同项目之间保持通用同时又不丢失项目针对性。模板库里存放的是“提问题的姿势”而 snippets 里提供的是“当前项目的答案”。一个容易犯的错是把项目上下文直接写进模板。短期看很方便但下一个项目用同一套模板时就会向 Claude Code 注入大量无用且可能混淆的信息。我发现一件挺有意思的事模板里的项目信息越具体换项目之后跑偏的概率越高。3.3 第三层任务描述与验收标准任务描述是整个模板中唯一应该每次新写的部分因为它天然是动态的。但我同样给任务描述设计了固定子结构。标准的feature.md任务区要求填写以下条目用户故事谁要做什么期望得到什么结果需求文档地址或链接如果有的话影响范围会改动哪些模块、涉及哪些接口变动验收标准至少三条可验证的完成条件非目标明确本次不做什么防止 AI 顺手越权“非目标”这条是我踩坑之后专门加进去的。Claude Code 很有“主人翁意识”经常在做 A 任务时顺便把 B 问题也“优化”了。如果 B 问题是真正的 bug 倒还好可怕的是它改了你设计之外的逻辑然后你 review 的时候根本反应不过来。所以在模板里我固定写上一句## 非目标 本次任务明确不包含以下内容 - {{ out_of_scope_1 }} - {{ out_of_scope_2 }}这个简单的约束至少帮我挡住了 60% 的“顺手优化式改动”。3.4 第四层输出格式与交付物定义对比下面两种模板写法哪种更可靠写法一“请帮我重构这个模块。”写法二## 输出格式 请按以下结构输出 1. 重构方案概览列出重构前后的结构差异 2. 改动文件清单每个文件的修改内容说明 3. 风险点说明哪些地方可能存在行为变化如何验证 4. 测试计划具体需要运行哪些测试命令 5. 提交信息建议给出一个符合项目规范的 commit 信息写法二看起来很啰嗦但它把“输出什么”和“先做什么后做什么”全都锁死了。尤其是风险点说明这一条等于强迫 Claude Code 在动手重构前先把自己的思路暴露出来。很多时候它在写“风险点”的过程中发现自己根本不可行就会主动停下来设计方案而不是直接改代码。我在所有模板的输出区都默认加上一个标记## 交付物 完成以上任务后需要检查的文件清单 {{ checklist_items }}有些任务天然不适合固定输出格式比如“回答一个技术问题”。那就用quick-question.md这样的模板输出结构只有一条“先给结论再给理由最后给例子。”实际上你不需要它输出太多只要让它的回答结构保持稳定就够了。4. 从模板到执行渲染机制和实际调用流程有了模板之后下一个问题是怎么让模板用起来最好的方式不是打开模板文件复制粘贴再把方括号里的变量一个个替换掉——那样你很快就不想用了。我实现了一套简单的渲染与调用流程让模板成为真正可执行的入口。4.1 变量校验让模板“知道你忘了什么”我用render_template.py处理模板渲染。这个脚本做的事情很简单读取模板文件解析它的 Front Matter提取variables列表也就是模板声明需要的外部变量在终端交互式询问缺失的变量把用户输入的值替换到模板的{{ variable }}占位符中渲染完成之后直接调用claude命令启动会话把渲染好的 prompt 作为输入。核心逻辑示意#!/usr/bin/env python3 import sys import yaml from pathlib import Path import subprocess def load_template(path): text Path(path).read_text() lines text.split(\n) # 简单解析 Front Matter暂不依赖复杂库 if lines[0] ! ---: raise ValueError(Missing front matter) end lines.index(---, 1) meta yaml.safe_load(\n.join(lines[1:end])) body \n.join(lines[end 1:]) return meta, body def render(template_path, values): meta, body load_template(template_path) for var in meta.get(variables, []): if var not in values: values[var] input(f请输入 {var}: ).strip() return body.format(**values) if __name__ __main__: template_name sys.argv[1] template_file Path(templates) / f{template_name}.md rendered render(template_file, {}) subprocess.run([claude, --print, rendered])出于演示目的这里做了很多简化。但你大概能看出意图渲染不是目的启动会话才是。4.2 组合式模板通用片段自动拼接真正让模板系统好用的是组合能力。feature.md的 Front Matter 里声明了related: - snippets/stack-context.md - snippets/coding-style.md渲染器在渲染feature.md时会自动把这些 snippets 的内容拼到## Context部分。这样使用者在跑python scripts/render_template.py feature的时候根本不需要操心“先描述项目结构再描述技术栈”这类重复劳动。我在实际使用中遇到了一个问题所有片段每次都拼进主题模板会让 prompt 变得很长在简单任务中反而不利。所以后来我加了一个可选机制related_optional: - snippets/security-checklist.md - snippets/deploy-steps.md渲染器运行时先用一个交互式列表问“是否包含这段信息”默认不包含。用户按一下回车就能跳过。这样模板就能在“完整”和“精炼”之间自由切换而不是所有任务都背着一堆无关的背景信息。4.3 在 Claude Code 之外维护一个“会话启动文件”除了单次任务的模板Claude Code 里我还会维护一个session-start.md用于每次打开新会话时建立基础上下文。它不是某个具体任务的模板更像是一个“前言”。实际起会话的流程是这样的第一次进入项目我先让 Claude Code 读一遍workflows/session-start.md这个文件告诉它项目的仓库用途、目录结构要点、常用操作命令、以及一些“绝对不要做”的底线之后的所有会话我都用一个短促的任务 prompt 开局因为它已经“自带记忆”了。Claude Code 本身会保留一些当前会话的上下文但只要你换了目录或者隔了几天之前的信息就会被冲淡。session-start 文件的意义就是让这些“常见上下文”不需要每次重新口头表述直接读文件就能快速恢复。很多人觉得“每次都要先读一遍文件”很笨。但实测下来这个时间成本比重新手写一遍上下文低一个数量级而且不会漏信息。这其实是团队中新人也能快速上手 Claude Code 的核心秘密。5. 容易翻车的三个地方我的经验与调整模板再完善实际跑起来还是会有一堆预期之外的情况。这里我把踩过的几个典型坑写出来每一个都对应一次真实的“返工现场”。5.1 一个冗长的背景信息能毁掉整个任务我最初写review.md代码评审模板时为了追求“完整”把项目的背景、团队历史、代码规范、命名约定、历史遗留问题整整写了两百多行。我以为信息越全评审越准。现实是那一次代码评审几乎没法用。它太关注我提供的那些“历史背景”了反而忽略了本次 diff 本身的逻辑问题。它给出的评审意见里有九成都是在重复我早就写在背景里的提醒真正基于 diff 新发现的 bug 少得可怜。这个现象背后的机制其实是注意力分配。长 prompt 里该关注的信息和冗余信息放在一起冗余信息往往先入为主占据大量理解空间。后来我把review.md的背景信息压缩成 5 行把注意力全部引导到“只看 diff”上效果立刻回升。经验教训模板里的上下文信息不是越多越好而是“够用就好”。你要做的是引导它把注意力放到本次任务的核心输入上而不是把自己知道的都塞给它。5.2 变量命名含糊等于没校验我一开始的变量名起得很随意比如目标、描述、约束。结果渲染器提示输入的时候使用者一脸茫然到底让我填什么后来我把每个变量名都改成“动词 名词”的结构variables: - 要实现的用户故事 - 需要保持不变的接口列表 - 本次禁止触碰的模块 - 已完成步骤的验收命令虽然有点长但在交互提示时特别清晰所有人都能一眼看懂这一栏里该填什么。与之对应模板里使用这些变量时上下文也会更自然请实现“{{ 要实现的用户故事 }}”。 注意保持“{{ 需要保持不变的接口列表 }}”中的接口签名不变。 禁止触碰“{{ 本次禁止触碰的模块 }}”中的任何文件。 完成时请运行“{{ 已完成步骤的验收命令 }}”并展示结果。用长变量名的代价是多打几个字收益却是零歧义。这个改变让整个渲染过程的填表体验从“猜谜”变成了“填空”。5.3 主动收敛模板的“自由尺度”Claude Code 对指令的执行有一个潜规则约束条件越模糊自由度越大越敢于发挥。当你的模板写了“请优化这个模块”它的发挥尺度往往超过你的预期当你写了“请优化这个模块但保持函数签名不变且新增逻辑必须单独抽成 utils 里的函数”它就老实很多。于是我把模板里的关键动词都做了“尺度限定”原表述限定后表述请优化这个模块请优化这个模块接口保持原样输出调整方案先输出调整方案我确认后再实施补充测试用例补充围绕现有测试框架的用例禁止新建框架完成代码完成代码并列出改动文件清单表面上是多写了几个字实际是开放了“先方案后执行”的模式。Claude Code 现在更像是先给我分析思路再动手实施而不是闷头干完以后丢给你一坨惊喜。我最喜欢的一个变化是把所有模板的动词统一从“请帮我把”换成“请先分析并说明在我确认后再执行”。这个句式的改变让对话节奏瞬间稳定下来很多之前“改了不该改的代码”的情况在这一步就提前拦截掉了。6. 把 claude-code-templates 变成团队的“操作系统”关于 claude-code-templates最后想聊聊它长期演进的一些思考。这套模板最初服务于我自己后来交给旁边几位同事用到后面就自然变成了团队共享的规范。一种比较有效的运作方式是模板库跟随项目库走谁提出模板改动谁负责更新 CHANGELOG。每周 review 一次模板的使用反馈把“这个输出结构不够简明”或“这个约束条件总是触发奇怪的解释”收集到 issue 里。任何模板改动都像代码评审一样先提 MR再合并避免“一个人悄悄改了模板其他人毫不知情”的情况。另外一个很好的用法是把模板库当作新人入职的“加速包”。新人只要把模板库和 snippets 读一遍配合 session-start 文件了解项目基本可以在一两天内完成从“不会用 Claude Code”到“能稳定产出合格任务”的过渡。这比他们自己摸索几十轮 prompt 要高效得多。而且模板库本身也可以被 Claude Code 消费。我会让它在进行某个模板的调整时先读一遍整个模板库分析各模板之间的结构是否一致再提出统一性改进建议。这样模板的维护也能借助一点自动化能力。6.1 给作者们的几个务实建议在你准备直接抄一个小模板库之前有五条建议第一从 3 个模板开始不要一上来就建二十个。先拿使用频率最高的三项任务写模板用熟了再扩展。模板库里真正有价值的不是数量而是每个模板都被反复用、持续改。第二每两周做一次“模板体检”把那些用过次数很低、或者输出质量总不稳定的模板拿出来重新审视。要么改要么删不要让它躺在目录里假装有用。第三保持模板的措辞像“人会说的话”。我见过一些模板为了“控制 CI 的行为”全篇都是“必须”“禁止”“务必”结果模型被约束得束手束脚输出极其生硬。最好的写法是“请先……然后……确认……避免……”这种自然指令流。第四不要只用一套模板处理所有任务。不同的任务对输出结构的要求差距很大混用会导致每次输出都要重新适应。第五把变量提示做得足够友好。渲染器的交互体验直接决定使用者想不想继续用模板系统你值得为它多写十几行代码。这些前提都做到了claude-code-templates 就不再只是一堆 Markdown 文件而是一个能持续产生价值的、团队可运行的系统。对于长期使用 Claude Code 的个人或团队来说这是一个投入产出比相当不错的确定性建构。