Claude Code 模板库实战：用提示词工程固化团队开发规范

1. 这套模板库到底在解决什么问题1.1 我为什么开始收集 Claude Code 模板先说背景。我大概在 Claude Code 刚开放命令行版本时就开始用了一开始对它最大的感受是很强但也很“飘”。它不像传统 IDE 里的插件那样有明确的配置面板一切交互都靠自然语言驱动。你用得好它是资深结对程序员用得不好它就是个答非所问的话痨。于是问题就来了同样一个版本库、同样一个任务有的人能让 Claude Code 自动完成一轮带单测的代码重构有的人却在上下文里反复纠正风格、解释业务背景、补充边界条件忙活一晚上也就改了半个文件。差别在哪差在你有没有给它一套稳定的、可复用的“工作方法”。claude-code-templates本质上就是一套给 Claude Code 使用的提示词、指令和配置文件的集合。我把它看作一个沉淀了团队规范和个人经验的“能力包”你把这些模板放进项目或全局目录之后每一次对话都自带这些背景和规则不用每次都把需求从头解释一遍。这不是什么魔法就是把重复劳动前置化让模型在动手之前就知道你想要的产出长什么样。1.2 没有模板时的典型翻车现场我先说几个我真实踩过的坑你看有没有同样遭遇。第一个是“答非所问型”。我让它“给这个函数补单元测试”它确实补了但用了项目里根本不存在的测试框架断言风格还是它自己编的。原因是我的项目里用了 pytest unittest.mock但对话里没交代它默认按它训练数据里最常见的 Jest 风格生成结果整个测试文件没法跑。第二个是“风格漂移型”。第一天让它写 Python 模块它写得挺规矩类型注解、docstring、异常处理都齐了第二天同样一个仓库它突然不写类型注解了函数命名也变成了另一种风格。原因是第一天对话里有人无意中说了“这个项目按 Google 风格来”第二天没人说模型就回到了默认习惯。这就是典型的口头约定失效没有固化成模板。第三个是“上下文爆炸型”。一个任务本来一两百行就能交代清楚但因为没有把仓库规则、目录结构、命令习惯提前放进模板我不得不在每次对话开头复制粘贴背景说明。一长串背景贴进去真正要干活的指示被挤到后面模型的理解重点反而错位了。这些问题的共性是“凭感觉协作”。人凭感觉猜模型的套路模型凭感觉猜项目的规则两个都猜不准。模板要解决的就是这件事把项目里稳定不变的东西抽取出来变成每次对话都自动加载的默认项让模型把注意力留给真正需要考虑的增量信息。2. 模板库的整体设计思路2.1 按任务类型分层而不是按语言分我在设计这套模板时第一原则是不要按编程语言去分而要按任务类型去分。市面上很多类似的提示词集喜欢分 Python 专用、JavaScript 专用、Go 专用我一开始也这么干用了一阵发现维护成本极高。因为实际任务里语言只是约束条件之一更关键的是“这件事怎么干”是修 bug、加功能、补测试、做重构还是做代码审查同样是“补测试”Python 项目和 TypeScript 项目的共同点远多于不同点都需要先摸清被测对象的行为都需要看已有测试的组织方式都需要保证新测试不破坏 CI。语言差异只是在最后“生成代码”这个环节体现出来。所以我做成了一套“任务型模板 技术栈扩展模板”的组合任务型模板管工作流如何理解需求、如何制定计划、如何动手修改、如何自检。技术栈模板管知识约束用哪个测试框架、遵循什么命名风格、依赖怎么管理。角色型模板管视角让你站在“代码审查者”还是“性能优化者”的角度思考。这三层叠起来就能覆盖 90% 的日常开发场景又不会因为新增一个项目语言而推翻整个模板体系。2.2 全局模板和项目模板拆开这套模板库还有一个核心决策把“通用规则”和“项目特化规则”拆成两层。我参考了 Claude Code 本身的机制。它支持项目级的CLAUDE.md文件放在仓库根目录每次会话启动就会自动加载也支持用户级的全局设置放在~/.claude/下。于是我把模板库分成global/和project/两个目录。全局模板放什么放所有项目都不会变的做事原则。例如修改代码前先解释你的理解和计划确认后再动手。代码改动必须与现有风格一致优先模仿同目录旧代码的写法。禁止在没有测试保护的情况下直接重构核心逻辑。每次输出代码都要给出简短的“改了什么、为什么改”说明。项目模板放什么放这个仓库特有的约束。例如这个项目用 pnpm 而不是 npm锁文件是pnpm-lock.yaml。API 错误统一返回{ code, message, data }结构。数据库迁移文件必须手写不允许用 ORM 自动同步。发布前必须跑pnpm lint pnpm test。这样拆分的好处很明显换项目时全局模板不用改项目模板跟着仓库走。我甚至会把项目模板提交到代码仓库里让团队所有成员共享同一套规则新人进来第一天就能让 Claude Code 按团队规范干活。2.3 模板的原子化是后期不烂尾的关键另一个让我受益很大的设计思路是“一个模板只干一件事”。早期我图省事把“代码审查”和“生成文档”塞进同一个模板文件里结果就是每次用它模型都搞不清你到底是要它找 bug 还是写说明文档常常两边都不讨好。后来我把所有模板都拆成原子化的片段每个片段只约束一个职责边界。比如审查模板只管挑刺列出问题清单不负责改代码重构模板只管按既定目标调整结构不做无关格式化补测试模板只管生成测试不顺手帮你优化被测函数。这样单个模板的指令长度很短模型遵循起来特别稳定。原子化还带来了一个额外的便利可以自由组合。我做了几个“组合模板”内部用分隔符把原子模板顺序拼起来。比如“重构并补测试”这个组合实际上就是“重构模板”执行到改动结束然后自动切换“补测试模板”接续干活。模型本身有不错的上下文理解能力只要每个阶段的指令边界清晰它就能顺畅地在不同工作模式之间切换。3. 核心模板拆解与实操要点3.1 CLAUDE.md让规则成为默认配置要说这套模板库里最重要的一个文件那一定是CLAUDE.md。它相当于 Claude Code 每次启动对话前自动读取的“公司章程”。我踩过很多次坑之后才意识到CLAUDE.md不是越长越好而是越“分层”越好。我见过有人把几千字的规范全部塞进去结果模型加载了大量冗余文字真正关键的约束反而淹没在里面。我的做法是控制在 150 行左右只用短句列事实不用长篇大论解释原因。举个例子我维护的某个 Python 服务项目CLAUDE.md长这样# 项目概览 - 这是一个 FastAPI 写的异步任务调度服务 - Python 版本 3.11包管理用 uv - 目录结构app/ 存放业务代码tests/ 存放测试migrations/ 存放 SQL 迁移文件 # 代码风格 - 类型注解必须完整禁止省略 - 函数 docstring 只写一句说明用途不写参数细节 - 异步函数必须以 async def 定义I/O 操作禁止用同步阻塞库 - 异常处理统一走 exceptions.py 里的自定义异常类 # 测试约定 - 测试框架用 pytest异步测试用 pytest-asyncio - 单测文件命名 test_xxx.py与模块同名 - 涉及外部 API 的测试必须打 mock不允许真实调用 # 常用命令 - 本地启动uv run uvicorn app.main:app --reload - 跑测试uv run pytest -q - 代码检查uv run ruff check .写的时候有几个要点。第一尽量用“禁止”“必须”这种强约束词代替“建议”“尽量”这种模糊词模型对确定性指令的遵从度要高得多。第二把命令写清楚这样它要跑测试或启动环境时不用猜。第三目录结构一定要写模型判断代码放哪、测试放哪基本就靠这段描述。3.2 任务型模板五个覆盖日常的高频场景我模板库里实际使用频率最高的任务型模板有五个需求拆解、代码修改、补测试、代码审查、重构。每一个都向模型描述了完整的执行流程而不只是一个目标。以“补测试”模板为例我给它定义了五步流程读取被测模块代码列出所有公有函数和类。检查 tests/ 目录下已有测试的组织方式和命名习惯。对每个公有函数先看已有覆盖率只补缺口。生成测试代码时边界值和异常场景必须覆盖接口 mock 清晰。写完后把测试跑一遍保证新增用例全部通过。这五步看起来简单但效果立竿见影。模板跑起来后Claude Code 会先自己列一个测试计划再动手而不是上来就写一大段重复代码。我最直观的感受是补出来的测试覆盖率从大概 60% 提到了接近 90%而且不再有“为了覆盖而覆盖”的无效断言。至于“代码审查”模板我要求模型输出统一采用“问题 严重级别 建议修改 对应文件行号”的格式并且明确划分阻断项和非阻断项。用了这个模板之后审查报告读起来舒服多了可以直接贴给同事看不用我再整理。3.3 角色型模板换一个视角看同一个仓库除了任务型模板角色型模板也很有用。所谓“换视角”就是让模型把注意力聚焦到一个特定关注点上。我最常用的角色型模板有两个一个是“安全审查官”专门扫描 SQL 注入、敏感信息硬编码、权限校验缺失这类问题另一个是“性能优化师”专门分析循环体、N1 查询、不必要的大对象拷贝。它们的写作方式和任务型模板不太一样。角色型模板不定义完整工作流而是定义“只看到什么、忽略什么”。比如安全审查模板的开头一段我写的是你现在是安全审查官。你只关心与安全相关的问题注入风险、越权访问、敏感信息泄露、不安全的反序列化、缺失输入校验。你忽略代码风格、命名规范、性能细节。发现问题时先解释攻击路径再给出修复建议。这段指令看似简单但对模型行为的影响很大。它会强制模型进入“专职扫描”状态而不是做一个全能评审。我在一次前端项目审查里靠这个模板发现了三个真实的越权接口都是平时人工 review 没注意到的。不过要提醒一句角色型模板的定位是辅助排查不是万能扫描器。它不能代替静态分析工具和渗透测试但它能在你改完代码之后快速给出第二双眼睛性价比很高。4. 模板怎么接入 Claude Code 并跑起来4.1 模板目录结构与存放位置整套模板我建议按这样的目录结构组织claude-code-templates/ ├── README.md ├── global/ │ ├── CLAUDE.md │ ├── code-review.md │ ├── write-tests.md │ ├── refactor.md │ ├── explain-code.md │ └── commands/ │ ├── review.md │ ├── test.md │ └── refactor.md └── project/ ├── python-fastapi/ │ └── CLAUDE.md ├── react-typescript/ │ └── CLAUDE.md └── go-service/ └── CLAUDE.mdglobal/下的文件是通用规则和通用模板project/下是按技术栈或项目类型定制的规则片段。commands/目录我单独说明它是用来实现自定义斜杠命令的。我把这套目录直接放在我自己常用的几个开发机里用软链接指到各项目的.claude/目录下。如果你们团队用 Git 协作更建议直接把CLAUDE.md提交进各自的项目仓库这样所有成员共享同一套规则。4.2 用自定义 Slash Commands 把模板做成指令自定义斜杠命令是模板落地最顺手的方式。我最常用的几个命令是/review、/test、/refactor它们其实都是把我前面写的原子模板压缩成一个短指令。实现方式不复杂。Claude Code 支持在.claude/commands/目录下放 Markdown 文件文件名就是命令名。比如.claude/commands/review.md就对应/review命令。文件里的内容实际上是一个高度精炼的指令集。以/review为例我文件里写的是对当前改动执行代码审查。按以下维度逐一检查正确性与边界条件、错误处理、性能隐患、安全问题、可读性。忽略代码风格问题。输出格式 1. 每条问题以 文件:行号 - 问题描述 开头 2. 标注严重级别阻断 / 严重 / 一般 / 建议 3. 阻断和严重级别的问题必须给出修复建议 4. 最后汇总一句总体评价写完这个文件我在编辑器里选中要审查的改动输入/reviewClaude Code 就会自动按这套格式执行审查。整个交互从一大段自由对话变成了一个稳定可复用的标准动作团队里其他人用起来也有统一预期。4.3 模板内容的版本管理与团队同步模板不是写一次就完事的它会随着项目习惯演变而调整。我用几个简单的办法保持版本同步第一模板库本身做成一个 Git 仓库每次修改都提交并写明原因。这样谁改了什么规则、为什么要改都有据可查。第二项目级CLAUDE.md和代码一起进同一个 Git 仓库。正好代码合并请求里如果改了测试约定或命令规范review 的人能看到这个变化团队就不会出现“代码改了但规范文档没跟上”的情况。第三定期做一次“模板瘦身”。我每两三个月会把模板里已经失效的规则清掉。比如某个项目原来用setup.py构建后来切到pyproject.toml如果没清理旧规则模型就会在新对话里混淆构建方式。保持模板和实际工具链同步比什么都重要。5. 实际使用中的问题与避坑清单5.1 模板越长效果越差原因不在模型我用这模板踩过的最大一个坑是一开始把CLAUDE.md写得太长。我原以为给的信息越多模型越懂结果恰恰相反。那一次我写了两百多行包含大量背景说明、设计理由、历史决策。模型确实读了但真正关键的执行步骤在超长上下文中被稀释了它在改代码时仍然按照自己的默认习惯来。后来我做了个对比实验同一份代码一个用精简到 80 行的CLAUDE.md一个用 200 行的详细版本各执行同样的重构任务。精简版的重构方案完全符合团队风格详细版反而出现了不少奇怪偏离。原因是很多“背景说明”其实与当前任务无关模型在读入的时候也抓不准优先级。所以我的经验是模板里只留事实描述和硬性约束一切“解释性”文字全部删掉。别写“这是一家金融公司的核心交易系统因此稳定性极其重要”直接写“该模块禁止使用淘金式异常捕获必须明确处理每个错误分支”就够了。模型不需要懂业务背景它只需要知道现在怎么做。5.2 角色模板互相打架怎么办当你同时用多套模板时可能出现“打架”的情况。我一开始把它当 bug 处理后来才意识到其实是一个优先级问题。典型场景是项目CLAUDE.md里规定了“所有对外函数必须写完整类型注解”但某个角色模板是“性能优化师”它为了减少运行时开销可能会建议去掉不必要的类型检查。这时候到底听谁的我的解法是在每个角色的模板开头加一句“优先级声明”。比如本模板专注性能优化。除安全问题外不改变项目的代码风格与类型规范。风格规范以项目 CLAUDE.md 为准。这句话本质上是在告诉模型你的任务是提建议不是改项目规则。有了这种优先级声明角色模板就只会聚焦在它该管的维度上不会越界推翻全局约定。类似的我还会在项目CLAUDE.md的末尾加一行“如果与项目内其他指令冲突以本文件的硬性约定优先”。5.3 模板没覆盖边界条件时代码仍然偏薄模板能规范流程但解决不了“模型想不到的边界情况”。比如我让它用模板生成一个文件上传接口它做得有模有样但没考虑磁盘满、文件名非法、文件大小超过限制这些分支。不是说模板没用而是模板要在流程上预留“自查边界”这一步。所以我在“代码修改”类模板里都加了一个固定步骤完成主逻辑后主动列出这个改动涉及的三类边界条件——输入异常、资源限制、并发冲突并确认每一类都有明确处理。这招非常管用因为它把“思考边界”从可选项变成了必选项模型每次都会真的停下来检查一遍而不是直接输出完事。5.4 多仓库项目怎么让模板不串味我会在多个项目之间切换最怕的就是上一个项目的规则串到下一个。比如一个项目禁用any另一个项目恰好相反模板如果不隔离模型就可能把上一个项目的禁any规则带过来。解决办法其实很简单项目级模板只放在项目仓库里同时全局模板保持最小化。不要试图建立一个“覆盖所有项目”的统一规范尤其不要在全局层写类似“所有 Python 代码必须做类型注解”这种话因为总有项目不这么要求。要紧的规则全部下沉到项目级全局只留最普适的协作原则。还有一个细节我会在切换项目时主动清掉 Clude Code 的旧会话而不是继续在一个会话里跨仓库对话。旧会话里残留大量上一项目的上下文比模板串味更难清理。新开一个会话让新项目的CLAUDE.md干净加载才是正确的用法。6. 从模板库到团队工作流的一点体会模板库做到这一步其实已经不只是一个技术分享了。我在实际维护中发现模板内容本身就代表了团队对“代码应该怎么写”的共识。今天你往CLAUDE.md里加了“禁止在业务层拼 SQL 字符串”明天模型就会严格警告任何人这么干今天你删掉了某条过时规则明天新人提交的代码就会立刻反映这个变化。所以我现在看这套模板库它更像是“把团队代码评审意见汇总成了一份可执行文档”。以前 code review 里反复提到的问题现在模型在生成阶段就提前避免了以前要花很多时间口头交代的项目背景现在模型天然就懂。省下来的时间被用在了更值得关注的事情上比如复杂业务逻辑的设计和跨团队协作。最后分享一个个人习惯我不追求模板大而全只保证每一条规则都是当前项目真正需要的。写进模板的每句话都要有对应的实际场景没有达成共识的规则绝不提前写进去。这个原则让我避开了所有“模板管理本身变成负担”的坑。模板是为干活服务的它永远不应该比干活本身更复杂。