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 的事件回调机制，适合把一些模板无须手动触发的动作自动化。我在模板仓库里配置了两个 hooks：SessionStart 时检查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 多人协作的模板库规范
当团队规模变大，模板仓库需要有自己的协作守则。我们目前的规定是：任何模板的增删改都要过 PR，PR 描述里必须写明使用场景、预期效果、与现有模板的边界；新模板先试用两周，收集反馈后再决定是否正式合入。这看起来像给一个私人小仓库套上了产品流程，但实际效果很好，因为模板质量的参差会在复制使用中快速放大，质量守门员越早介入，后期返工越少。
最后分享一条我自己的体会：做模板库最忌讳的是"为了整理而整理"，模板本质上是经验的封装，没有真实项目反复打磨过的模板，写得再漂亮也是空壳。如果你的项目还在快速迭代期，建议先把精力放在业务代码上，等你在几次对话中明显感到"这套 prompt 我很满意、希望以后还能复用"时，再把它抽出来沉淀成模板——那时候你写的每一个字都有来路，这个模板库才真正立得住。
