1. 项目从哪来为什么我把零散的 Claude Code 提示词沉淀成模板库先说个场景。刚开始用 Claude Code 那阵子我干过不少重复劳动每次让它写一个新功能都要现场组织一大段提示词把技术栈、目录结构、编码习惯、输出要求从头交代一遍。运气好的时候对话风格和结果都挺理想但当天的手感就丢了第二天换个问法输出质量立刻打对折。最典型的一次我让 Claude Code 帮我生成一套后端接口的单元测试同一个服务周一写得还像模像样到了周三换了个说法描述需求它给出的测试用例就直接跑偏连 mock 的对象都不对。后来我在团队里复盘这事儿发现问题的核心不在 Claude Code 的能力而在我的输入没有标准化。人类工程师接手一个模块前会先看项目文档、历史代码、团队规范形成一套稳定的上下文但 CLI 对话是无状态的每次新对话都是重新开始。于是我就有了做 claude-code-templates 的想法把那些用下来效果稳定的提示词、角色设定、任务拆解方式、输出格式约束统一整理成模板文件放进仓库用的时候直接取不再每次从零开始组织语言。这个仓库本质上记录的不是怎么写代码而是怎么和 Claude Code 沟通。它的使用对象有两类第一类是刚接触 Claude Code、不知道从何下手的开发者他们缺的是一份可以照着抄的标准答案第二类是已经用得比较熟练、但苦于团队输出风格不一致的人他们需要的是把个人经验固化成可共享的资产。我最初做这个仓库只是为了自己省事结果一次团队分享把仓库发出去之后好几个同事都开始基于里面的模板改自己的工作流那之后我才意识到这东西的复用价值远超预期。仓库本身的结构并不复杂核心就是几条原则模板要有明确的分类不要一锅炖模板之间要能组合不要互相割裂模板的表述要足够冷去掉那些只适用于某一次对话的上下文留下可迁移的部分。后面我花了大半年时间反复打磨这套结构走过不少弯路这里把最终沉淀下来的东西完整拆解一遍。2. 仓库架构设计目录怎么摆、文件怎么命名、版本怎么管模板仓库最容易犯的错是把所有 markdown 文件往一个目录里一扔靠文件名区分用途。两个月之后你自己都分不清prompt_v3_final.md和prompt_v3_final2.md到底哪个是对外用的。所以我把仓库搭成了下面这个样子claude-code-templates/ ├── CLAUDE.md # 项目级记忆文件Claude Code 每次会话自动读取 ├── README.md # 仓库入口说明各目录用途和使用方式 ├── .claude/ │ ├── commands/ # 斜杠命令注册目录一个 md 文件对应一个 /命令 │ │ ├── code-review.md │ │ ├── test-generate.md │ │ ├── bug-hunt.md │ │ ├── commit-message.md │ │ └── api-doc.md │ └── settings.json # 编辑器集成与行为开关配置 ├── templates/ │ ├── 01-role/ # 角色模板约束 Claude Code 以什么身份工作 │ │ ├── backend-architect.md │ │ ├── frontend-specialist.md │ │ ├──>--- role: backend-architect version: 1.1.0 deprecated: false --- 你是一名有 12 年经验的后端架构师擅长分布式系统设计与 API 建模。 在回答本会话中的所有问题时请遵循以下行为准则 1. 优先关注扩展性和可维护性而非短期实现速度。 2. 设计方案时必须明确说明取舍trade-off禁止给出没有权衡的最优解。 3. 涉及数据库建模时先指出可能的查询模式再给表结构。 4. 不要直接输出完整代码除非用户明确要求。默认以接口签名、结构说明、关键伪代码为主。 5. 当用户的需求存在歧义时主动列出假设并请求确认不猜测需求。写这个角色模板时我刻意避开了几个常见误区。不要过度输出完整代码这条就是血泪教训——如果不约束Claude 会默认生成一大段可运行代码把设计讨论完全淹没掉你本来想聊接口规划结果得先花时间审它五百行代码。明确说明取舍则是我最看重的行为约束实践中没有这句时Claude 往往只给一个方案方案背后的考虑完全不可见。角色模板本身不承载具体任务所以它通常与任务模板连用。连用方式有两种对话开始前让 Claude 先读角色模板再开始干活或者在任务模板的头部加一行你是一位严格遵循 backend-architect 行为准则的工程师。我推荐后者因为角色模板一多全部塞进上下文会浪费窗口只把行为准则摘要织进任务模板角色模板留作人类阅读的参考文档即可。3.2 任务模板把需求变成可执行的动作序列任务模板是整个仓库的使用主力。它负责把帮我写个登录注册这种模糊请求转译成一串 Claude 能直接执行的动作。我的templates/02-task/feature-dev.md核心段落如下--- task: feature-dev version: 1.3.0 deprecated: false --- ## 目标 实现用户指定的功能需求交付可运行、可验证的代码变更。 ## 执行步骤 1. 阅读项目根目录的 CLAUDE.md提取技术栈、目录结构、代码风格约束。 2. 列出当前新增功能涉及的文件清单标注新增/修改状态等待用户确认后再动工。 3. 按先接口层 → 再服务层 → 最后持久层的顺序实现每完成一层停 5 秒并请用户确认接口签名。 4. 所有业务逻辑必须附带单元测试测试文件与被测文件置于同一模块目录下。 5. 完成后输出变更摘要格式参考 summary-format 模板。 ## 验收标准 - 项目现有测试全部通过。 - 新增功能路径有测试覆盖关键分支覆盖率不低于 80%。 - 代码符合项目 .editorconfig 与 lint 规则无新增警告。这个模板我做了一次关键调整把较长的步骤说明压缩成了先接口层→再服务层→最后持久层这样带有明确顺序要求的动作序列。最早的版本里我会写上请充分考虑现有代码的扩展方式事实证明这类模糊期望毫无约束力Claude 看到等于没看到它自己会按最顺手的路径来。而动作序列必须具体到第 N 步做什么、做完要等谁确认Claude Code 才能像执行脚本一样推进。当然任务模板不能一板一眼到完全机械化否则遇到特殊情况会僵住。所以我在模板里加了每完成一层停 5 秒并请用户确认接口签名这样的检查点本质上是用用户介入来兜底避免 Claude 按错误的接口假设一路写到底。半年前我用这种带检查点的方式带三个初级开发用 Claude Code 写新模块返工率比裸提示词降低了六成。3.3 格式模板强制输出结构的最后一道闸门格式模板不参与逻辑思考只约束交付物外观。templates/03-format/commit-message.md是最简单的例子--- format: commit-message version: 1.0.2 deprecated: false --- 根据 git diff --cached --stat 的输出生成符合 Conventional Commits 规范的提交信息。 要求 1. 主语一律使用现在时祈使句形式Add/Fix/Update/Refactor。 2. scope 从变更文件的目录名中提取无明确目录时省略。 3. body 部分最多写 3 条要点每条不超过 80 字。 4. 不得在提交信息中出现文件名或行号引用。 5. 输出格式统一为 type(scope): subject - 要点 1 - 要点 2这类模板的写作要点是把输出结构描述到机器可判定的程度。我见过很多人写格式模板时会写请用规范的中文提交信息这种话一文不值因为 Claude 的判断标准和你的判断标准完全可能是两套。把规则细化成scope 从变更文件的目录名中提取不得出现文件名或行号它才能每次都产出接近你想要的东西。格式模板可以解决一个隐蔽问题Claude Code 在不同的上下文长度下输出格式稳定性会下降。对话轮次多、上下文接近窗口上限时它给出的 Markdown 结构容易飘表格列数会变、代码块语言标注会丢。把格式约束单独抽成模板并多次强调能将这种输出劣化控制在一定范围内。虽然不能根除但至少比裸问好得多。4. 把模板真正接进 Claude Code 工作流静态模板文件只是原材料真正让 claude-code-templates 发挥价值的是与 Claude Code 原生机制的整合。这一节说三个层次的接入方式。4.1 CLAUDE.md 的作用边界我在模板仓库里的CLAUDE.md只写与维护和使用模板有关的公约。比如哪些目录放角色、哪些放任务模板之间禁止互相复制大段内容而必须通过$REF占位符引用等等。它解决的是用户拿到仓库后如何与 Claude Code 协作维护这套模板库这件事。CLAUDE.md 最容易犯的错就是把它当成万能的项目说明喜欢什么就写什么。写技术栈、写 API 认证、写团队架构越写越长。但 CLAUDE.md 是每次会话都会读入的固定开销写个几千字等于每次开头白白烧掉几千 token 的窗口。我建议 CLAUDE.md 只放必须永远遵守的约束把可变的、临时的、长度超过 200 字的内容全部拆到templates/下的独立文件里按需引用。4.2 用斜杠命令把常用模板变成/命令Claude Code 的斜杠命令机制是模板仓库落地最爽的一步。在.claude/commands/下放一个 markdown 文件就自动注册了一个命令。例如code-review.md文件内容如下--- description: 对指定文件或当前 git diff 执行代码审查 argument-hint: [文件路径 | 留空表示审查当前 diff] --- 按照 templates/02-task/code-review-session.md 中的流程执行代码审查。 重点检查并发安全性、错误处理完整性、与现有模块的一致性。 输出审查结论时遵循 templates/03-format/code-review-report.md 的格式要求。每次在终端里敲/code-review加上参数Claude 就会自动读取命令文件、按任务模板走流程、最后按格式模板出报告。整个过程不依赖你临时写任何一句话相当于把全套工作流固化成了一个可反复调用的函数。使用这个机制有两个坑要注意。第一命令文件路径里的模板引用要用相对当前工作目录的完整相对路径不能只写文件名否则 Claude 找不到文件时可能自行发挥。第二命令文件不适合写太长它会占据重要的指令位置。如果某个流程的完整定义超过 300 字正文里用一行引用模板文件不要全文抄进来。4.3 hooks 自动化把模板触发的活交给脚本hooks 是 Claude Code 的事件回调机制适合把一些模板无须手动触发的动作自动化。我在模板仓库里配置了两个 hooksSessionStart 时检查templates/目录是否有比CLAUDE.md中登记的内容更多的新模板文件有则提示更新注册表UserPromptSubmit 时如果检测到 prompt 中出现写测试关键字自动在 prompt 前面拼入templates/02-task/unit-test-generation.md中关于测试框架和 mock 风格的约定。hooks 的配置写在.claude/settings.json里JSON 结构大致如下{ hooks: [ { matcher: SessionStart, hooks: [ { type: command, command: python3 scripts/check-consistency.py } ] } ] }这里我不建议一开始就上复杂的 hooks 逻辑。hook 是在模板机制之上加的一层自动化模板还没用熟就自动化出问题时排查链路非常绕。先把模板和斜杠命令跑顺再逐步把每次都要手动提醒的环节请 hooks 接管这个顺序更稳妥。注意hooks 的每个事件都可以绑定多条命令Claude Code 会顺序执行任一命令以非零状态退出即终止。设计 hook 命令时要保证幂等和轻量不要在 hook 里跑重量级构建或全量测试否则你会一边等 hook 一边骂自己当初为什么这么写。5. 维护一年多踩下的坑与取舍模板仓库不像应用代码写一遍就完事。它需要持续维护而维护过程中我踩过不少坑这里挑最有代表性的三个说。5.1 模板长度失控从全文 prompt 退化到骨架式模板最早的几版模板我把好的提示词理解为详细的提示词一个任务模板动辄写 800 字把背景知识、技术选型理由、代码风格示例全部塞进去。实际用下来问题立刻出现Claude Code 是会把模板整段读进的800 字的模板一上场上下文就被吃掉一大块留给真正代码分析的余量就少了更麻烦的是模板里的背景知识与当前项目实际情况常常冲突导致 Claude 拿着旧上下文来硬套新问题。现在的写法是骨架式模板只描述动作序列和决策原则所有项目相关的具体信息留到对话时实时注入。比如测试生成模板里不写项目使用 JUnit 5而是写阅读项目 CLAUDE.md 或构建文件确认测试框架后按该框架生成测试。骨架式模板的单个文件长度被我压在 200 行以内实测上下文开销小了一半适配性反而更好。5.2 上下文窗口的浪费无关模板会污染对话模板管理里有个隐蔽的浪费一次会话中加载了过多个模板。Claude Code 的上下文窗口是共享的每加载一个模板就占用一部分容量而真正对当前任务有用的可能只有其中一小段。我早期会在对话开头把角色模板、任务模板、格式模板一股脑全塞进去结果 Claude 的注意力被分散经常在输出格式上特别正确在业务逻辑上反而不够深入。后来我对加载什么模板做了严格分层只有任务模板是每次必须加载的角色模板默认不加载只有在对话跑偏到方案风格不对时再补一句请以 backend-architect 模板的行为准则输出格式模板则在需要交付物时才指定引用。这样调整之后单次会话的有效上下文比例上来了复杂任务的处理质量提升明显。5.3 单一模板兼容性陷阱参数占位符的冲突与隔离模板里经常需要占位符比如{{FEATURE_NAME}}、{{MODULE_PATH}}。问题在于模板组合使用时占位符名可能撞车。我的格式模板里用{{TYPE}}表示提交类型任务模板里用{{TYPE}}表示文件类型两者一旦在同一会话中同时加载就是个隐患。Claude 有时候能根据上下文推断有时候就真用错。我的解法是在不同层级的模板里给占位符强制加前缀角色层用R_任务层用T_格式层用F_比如T_FEATURE_NAME、F_COMMIT_TYPE。虽然看着丑了一点但在组合模板时几乎杜绝了歧义。命令行参数与模板占位符的隔离也得注意斜杠命令的$ARGUMENTS是独立的变量不要在模板正文里混写$ARGUMENTS和{{...}}Claude Code 对这两套变量的解析时机不同混写的文件很容易出现参数没传进去的诡异情况。6. 从能用到好用模板库的演进路线仓库运行到现在我的重心已经从写模板转移到了让模板可持续演进。最后分享几条正在实践的方向供参考。6.1 统计调用频次淘汰僵尸模板模板也会僵尸化。团队引入某个模板后热情消退调用频率逐步下降但文件一直留在仓库里给人一个这是被认可的最佳实践的错觉。我目前在斜杠命令的模板注释里埋了一个计数标记每次通过命令调用就把次数写到一个本地统计文件里每月看一次连续两个月调用次数为 0 的模板进入淘汰评估。不是说调用少就一定要删而是需要人工判断它是否仍有价值没有价值就标记deprecated: true移到archive/目录。6.2 让模板可组合入口模板 片段库模板之间需要良好组合性。当前templates/三层分类已经是组合的基础我下一步打算引入片段库把那些特别短的、经常被复用的规则片段比如未经确认不得修改公共接口签名错误处理一律返回结构化错误码放到fragments/目录里由上层模板在运行时按其语义拼接。这样粒度更小、可维护性更好也更方便在团队之间共享。6.3 多人协作的模板库规范当团队规模变大模板仓库需要有自己的协作守则。我们目前的规定是任何模板的增删改都要过 PRPR 描述里必须写明使用场景、预期效果、与现有模板的边界新模板先试用两周收集反馈后再决定是否正式合入。这看起来像给一个私人小仓库套上了产品流程但实际效果很好因为模板质量的参差会在复制使用中快速放大质量守门员越早介入后期返工越少。最后分享一条我自己的体会做模板库最忌讳的是为了整理而整理模板本质上是经验的封装没有真实项目反复打磨过的模板写得再漂亮也是空壳。如果你的项目还在快速迭代期建议先把精力放在业务代码上等你在几次对话中明显感到这套 prompt 我很满意、希望以后还能复用时再把它抽出来沉淀成模板——那时候你写的每一个字都有来路这个模板库才真正立得住。
