从接手一个遗留服务端的重构、到给新项目定初始目录结构，我在终端里跟 Claude Code 打交道的时间估计有半年了。最开始我的用法很粗暴：把需求整段贴给它，让它“看着办”。一段时间用下来，发现它的输出质量波动非常明显，同样的任务，有时候能拿出几乎可以合并的代码，有时候却会在一个无关紧要的函数上绕来绕去。后来我意识到，问题不是模型变笨了，而是我从来没有告诉它“这次任务的边界、约束和验收标准是什么”。于是我把自己一次次调教出来的指令整理成了模板，就有了这个叫 claude-code-templates 的仓库。它本质是一套面向 Claude Code 的可复用提示词模板，覆盖代码评审、重构脚手架、技术方案设计、目录规划、bug 排查这些高频场景。我不指望它替代你写代码，但如果你也在用 Claude Code 做实际工程交付，这套模板能让你少走很多来回试错的弯路。
下面我尽量把整个项目的设计思路、模板结构、实操记录和踩坑经验一次讲透。
1. 项目整体定位：为什么 Claude Code 需要一套模板体系
1.1 裸奔式对话的最大问题是“上下文失忆”
先说个现场。有一次我让 Claude Code 给一个 Python 服务增加分布式锁，需求描述得很完整，包括用哪个库、锁的 key 规则、超时时间。它写出来的第一版代码是对的，但紧接着我让它“顺便看一下旁边那个模块的导入路径有没有问题”，它忽然就不再关心刚才那个锁了，而是开始审视整个项目风格，甚至自作主张改了几处命名。很典型对吧？这种“越聊越飘”的现象，我在很多用 AI 编程工具的同事那里都听到过。
原因其实不复杂。Claude Code 的本质是一个带工具调用能力的对话式编码代理，它每次能记住的上下文是有限的。你在对话里说了十个要求，它在执行综合任务时可能只会重点照顾最近的两三个。它不是故意漏掉，而是注意力分配和上下文窗口限制叠加的结果。模板的作用，就是把那些“不能忘、必须守”的约束，在任务开始前用结构化方式钉进上下文里。
我常常打一个比方：不带模板跟 Claude Code 协作，就像把一个实习生拉到没写制度的项目组，你交代一句他执行一句；带模板，相当于先给他一本带检查项的作业手册，哪怕你中途不盯着，他也会照着验收标准自查。
1.2 这个项目到底解决什么问题
claude-code-templates 不是把网上抄来的提示词堆在一起，它解决的是四件事：
第一，输出稳定性。同样的输入条件下，用模板和不用模板，代码风格、边界处理、测试覆盖率都会有肉眼可见的差别。模板里的约束越多，Claude 的自由发挥空间越小，产出越接近你能预测的样子。
第二，上下文复用效率。很多提示词写一次是浪费，写十次就是负担。模板把那些反复使用的系统角色、输出格式、禁止事项固化下来，每次调用成本几乎可以忽略。对于团队协作的场景，你甚至可以把模板提交到仓库里，让所有人都按同一套标准跟 AI 协作。
第三，可验证性。我写模板时强制要求每份模板都携带验收标准，Claude 执行完任务后必须逐条对照说明结果。这让你能在几秒钟内判断它有没有跑偏，而不是再去肉眼 review 每一行改动。
第四，领域沉淀。模板不是一次写死的，它是活的。我在跑完一个重构项目后，会把这次项目里出现的“典型问题”追加到对应模板里。三个月下来，这套模板已经不像通用的提示词，更像是我这个团队对这个代码库的“AI 协作约定”。
1.3 适合谁来用
如果你符合下面任意一条，这个项目的思路值得参考：
- 日常用 Claude Code 做代码生成、重构或者 Code Review，但是觉得输出质量忽高忽低。
- 团队里多人都在用 AI 编程工具，但每个人调出来的水平参差不齐，缺少统一标准。
- 你想把 Claude 用在“有一定风险”的改动上，比如数据库迁移、权限模块调整，需要它严格按步骤执行，而不是自由发挥。
- 你受够了每次开新任务都要重新把一大段背景需求打一遍。
反过来，如果你只是偶尔用 Claude 问一两个语法问题，或者纯粹想闲聊式写代码，那这套模板对你来说确实有点重。它不是给轻量场景准备的，是为工程化使用准备的。
2. 模板库的核心设计思路与拆解
2.1 设计原则：按“任务风险”聚类，不按“行业场景”聚类
这套项目一开始差点被我做成一个“什么都放”的提示词库，模板按前端、后端、测试、运维去分。很快我就发现这个分法不好用。原因很简单：同样是“后端任务”，改一个配置文件的风险和改一个支付回调的风险完全不一样。行业场景是表象，任务风险才是影响协作方式的真正变量。
所以最终我把模板分成了五个层级，从“低风险探索”到“高风险变更”依次排列：
- 探索型任务：点子评估、技术选型比较、目录结构规划。这类任务允许 Claude 发散，重点是输出比较和理由。
- 生成型任务：创建新模块、写初始脚手架、生成单元测试。需要给出明确的文件路径和命名规范。
- 修改型任务：修 bug、优化局部实现、调整接口签名。必须限定影响范围，要求它先说明改动波及面。
- 评审型任务：Code Review、安全检查、依赖风险评估。需要它保持挑刺视角，禁止“这代码没什么问题”这类敷衍式结论。
- 高风险变更：重构核心模块、数据库字段变更、权限相关调整。强制要求分步骤执行、每步验证、回滚预案。
这样设计有个直接好处：我在找一个模板的时候，不是在想“这是哪类业务”，而是在想“这次改动我敢不敢让 Claude 直接动手”。前者是经验判断，后者是风险判断。风险判断才是控制质量的关键。
2.2 文件组织与可组合性设计
仓库目录我用的是按风险等级加原子能力混合的方式。项目里有一个 templates 目录，里面每个模板是一个独立 Markdown 文件，文件名就是模板的名字：code-review.md、refactor-stepwise.md、bug-locate.md、plan-design.md、scaffold-module.md 这些。
这些模板不是互相孤立的，它们遵守一个“基础约束 + 增强模块”的组合原则。比如base-rules.md是每一份模板都会引用的公共约束，内容包括：禁止在没有测试的情况下直接改生产代码、修改文件前必须先用相关工具确认当前内容、输出代码必须附带简短改动说明。而每个具体模板里，只写跟本任务强相关的特殊约束。
举个例子。refactor-stepwise.md的完整结构大致是：
# 任务：渐进式重构 你在执行一个渐进式重构任务。你的目标不是一次性重写，而是在保持功能不回归的前提下， 分多次小步完成结构调整。 ## 执行前 - 先读取目标文件和它的调用方，列出现有依赖关系。 - 不要修改任何未被要求重构的文件。 ## 执行中 - 每完成一个步骤，必须确认当前代码仍能通过静态检查。 - 一次只改一个逻辑单元，禁止顺手优化无关代码。 ## 输出格式 - 给出重构前后的关键差异摘要。 - 列出每个步骤的修改文件清单。 - 针对每项改动，说明“为什么这么改”。这种写法说白了就是给 Claude Code 划定边界。它仍然可以发挥能力，但它的发挥被限制在安全范围内。
2.3 模板里的“锚点”与“验收条款”
所有模板都包含了两个核心部件：锚点和验收条款。锚点是指告诉 Claude“你要以什么身份、围绕什么主线来行动”的那句话。我见过很多提示词，全篇都在讲“要做什么”，却从头到尾没有一句话讲“你是谁、判定标准是什么”。Claude 在缺乏锚点的情况下，容易把自己当成一个通用问答助手，而不是一个“正在处理本次代码变更的工程师”。
下面是几个我从实践中提炼出来的锚点写法，你可以直接参考：
- “你是一名有 10 年经验的 Python 后端工程师，这次只负责代码评审，不负责修改代码。”
- “你是一个对性能敏感的 SRE。你看到的每一段查询，都要先问执行计划会怎么走。”
- “你是该模块当前的主要维护者。你需要在改动前评估是否会影响线上兼容性。”
锚点之后紧跟验收条款。我会要求它最后输出一份 Check 列表，逐条确认自己做的事项。比如对代码评审模板，验收条款就是：是否发现了至少两个真实问题、是否指出问题发生的上下文、是否给出了可用修改建议。这个设计像一个钩子，逼着 Claude 把思考过程显性化。没有这份 Check 列表，它极容易输出一堆“整体质量不错，建议增加日志”之类的正确废话。
3. 实操环节：从零搭建你的 Claude Code 模板库
3.1 第一步：确认你的 Claude Code 工作目录结构
Claude Code 在项目中会读取一个叫 CLAUDE.md 的文件作为项目的长期记忆。这个文件非常适合存放那些“跟具体代码库绑定的、长期不变”的规则。比如你这个项目不用 TypeScript、测试命令是 pytest、禁止修改某个自动生成目录，都写在 CLAUDE.md 里。
如果你希望在启动某类任务的时候能主动加载一段提示词，可以把模板放到.claude/commands/目录。这一层是适配 Claude Code 自定义指令能力的最佳实践。目录结构大概长这样：
your-project/ ├── CLAUDE.md # 项目级长期规则 ├── .claude/ │ └── commands/ │ ├── review.md # /review 触发代码评审 │ ├── refactor.md # /refactor 触发渐进式重构 │ ├── design.md # /design 触发方案设计 │ └── scaffold.md # /scaffold 触发模块脚手架生成 └── docs/ ├── templates/ │ ├── base-rules.md │ ├── code-review.md │ └── refactor-stepwise.md我在实际项目里会把CLAUDE.md写得非常简短，只放极少数关键规则，比如“本项目测试必须通过后才能提交”“目录generated/的内容禁止手动修改”。那些更复杂的、按任务触发的内容都放到commands/里。为什么这样分？因为CLAUDE.md里的内容会在每次会话开始时被加载，文字越多，挤占的上下文越多。而 commands 里的大段提示词只在触发时进入上下文，按需取用，不浪费资源。
这里有一个很重要的实操细节：CLAUDE.md不要写成一份长篇大论。我自己一开始把整个代码规范、命名规范、部署流程都塞进去了，结果发现 Claude 反而把规范当成参考素材，而不是必须约束。精简之后，只保留“违反就会出大问题”的硬规则，效果反而好了。这一点大家务必记住。
3.2 第二步：从最高频的 3 个模板开始写
不要一上来就尝试写完 20 个模板，那是做玩具。真实工程里，最高频的无非是三个：代码评审、bug 定位、模块生成。先把这三个写透，用起来，再看缺什么补什么。
拿代码评审模板举例，我分享一份现在仓库里最核心的版本：
# 代码评审任务 你是一位严谨的代码评审者。你的目标不是夸奖代码，而是找出修改合并前必须解决的真实问题。 ## 评审范围 - 只评审用户指定的 diff 或文件。 - 不评审任何未经确认的假设。 ## 评审维度 1. 逻辑正确性：是否存在边界条件遗漏、状态未清理、并发问题。 2. 安全性：输入校验是否完整，是否有越权或注入风险。 3. 可维护性：命名和结构是否清晰，是否存在复制粘贴代码。 4. 性能：是否存在明显可避免的循环嵌套、N+1 查询或重复计算。 ## 输出格式 用以下结构逐条输出： ### 问题列表 - 严重程度：高/中/低 - 问题描述：一句话说明问题是什么 - 位置：文件路径和大致行号 - 为什么是问题：给出触发场景 - 修改建议：具体到可执行的级别 如果没有发现问题，必须明确写出“未发现问题，但以下几点值得关注”，不允许只说“代码质量良好”。这份模板看起来不长，但它其实把评审员的角色、审查的维度、输出的结构化格式全部钉死了。我用它跑过的评审，质量稳定在一个很理想的水平：至少能发现 2 到 4 个需要讨论的真实问题，而不只是一句“LGTM”。
为了接住“组成部分”，注意这之后的内容还是继续，加上 bug 定位的例子。再接着写“为什么 bug 定位要限时限步骤”“为什么用了二分式的指令”。
3.3 第三步：为模板加上有效的“验证回路”
模板写出来不等于模板有效。你必须在接下来的几个项目里持续验证它。我判断一个模板是否有效的标准就一个：使用这个模板后，返工修改的比例有没有显著降低。
具体怎么验证？我在实验期里会做一个简单的记录表，每次任务跑完都记三个字段：任务类型、返工次数、返工原因。返工原因里如果反复出现“Claude 忽略了某条约束，我又在后续对话里重新强调了一遍”，说明这条约束的位置或者表达方式有问题。这时我就调模板，把那条约束往前提一个层级，或者改成加粗显式措辞。
举个例子。我的 code-review 模板最初没有“不允许只说代码质量良好”这条硬性约束，结果有两个任务里 Claude 输出的评审内容几乎没有实际价值，全是泛泛而谈。加了这条约束之后，几乎再没出现过空泛结论。
3.4 关于 token 成本的一个实在建议
我知道有人会担心模板太占 token。这个担忧是对的，模板确实会消耗上下文。但关键是得算账。一个代码评审模板大约 400 到 600 个 token，这个量对于动辄几千上万个 token 的代码文件来说，占比很低。它的价值在于减少了 N 轮“你怎么没按我说的做”“请你重新考虑一下刚才那个问题”的来回。每一轮来回都可能吃进去上千 token。所以我测下来的结论是：用模板反而省 token。
真正需要警惕的模板不是太长，而是针对性太弱。换句话说，一个写满了无关行业知识的模板才会劣化效果。比如你给日常 CRUD 项目套一个大型分布式系统模板，里面全是熔断、限流、数据一致性条款，Claude 就很容易把简单问题复杂化。模板的使命是让任务边界清晰，不是让任务变重。
4. 实战复盘：模板驱动的一次真实重构记录
4.1 前情提要：一道看似简单但容易失控的任务
我带团队维护过一个内部报表服务，代码用 FastAPI 写的，历史包袱不轻。需求是把其中一个核心的数据查询模块拆成独立查询服务，同时保持对外接口不变。
这类任务最危险的地方在于：查询模块跟授权、缓存、日志等多处逻辑纠缠，如果你让 Claude 一次性重写，出来的代码大概率功能“看着对”，但在异常处理、权限判断这些边缘场景上悄悄退化。我以前就吃过这个亏，所以这次从一开始就走 refactor-stepwise 模板。
4.2 具体执行流程记录
整个流程分成了五个阶段：
第一阶段，让 Claude 读目标文件和相关调用方，输出依赖清单。模板中“执行前必须先读取调用方”这条约束在这里起了大作用。它给出的清单里有三个我当时都不太确定的隐式依赖，节省了后续排查的时间。
第二阶段，制定迁移计划，但明确要求“最优小步”。Claude 在模板约束下，给出的计划不是一步到位的大迁移，而是一个围绕接口拆分的渐进序列。我在中途手动调整了两个步骤的顺序，其余都保留了。
第三阶段，按照计划逐小步执行。每步执行完，我要求 Claude 先运行静态检查和现有测试，再继续下一步。这一步看似拖慢节奏，实际上避免了最危险的“跑完全部测试后不知道哪里坏了”的黑洞式排错。
第四阶段，全部完成后，进行一轮全面的代码评审。由于改动涉及多文件，这次评审用的是 code-review 模板的完整版。它指出了一个我在人工阶段没注意的问题：新拆出的服务中，有两个参数在异常路径上没有做默认值保护，会导致特定情况下 500 错误。这是这次项目里最有价值的发现之一。
第五阶段，收尾清理。让 Claude 检查是否有孤立 import、死代码、废弃注释，输出一份清理清单。注意，这一步也是模板里预留的“收尾锚点”，避免任务结束时上下文还停留在代码逻辑上。
4.3 实验观察结果与感受
同一个项目我曾经在早期没有模板时也尝试过一次。当时我让它直接重构，结果它在第三次交互后忽然连一个无关模块的命名风格都开始“优化”，导致 diff 里混进了一堆噪音。这次的模板版本则完全不同，全程几乎没有无意义改动。
坦率地说，模板并不能让 Claude 自己变得更聪明。它真正的作用，是逼着我在任务开始前把抽象需求翻译成边界清晰的指令。很多项目失败的根源，不是模型能力不够，而是人在描述任务时就漏掉了关键约束。模板暴露的是我自己的思考漏洞，这一点很反直觉，但是真的。
5. 常见问题与排查技巧实录
5.1 模型不遵守模板里的约束，怎么办
很多人第一次用模板会遇到的第一个问题是：Claude 明明看到模板写着“不要修改无关文件”，还是顺手改了。这种情况通常不是模型故意抗命，而是模板里的约束淹没在一大堆文本里。解决办法有三个。
- 把约束拆成逐条列表，而不是长篇散文。
- 把“最不能违规的一条”放在模板最前面，用一句完整短句强调。
- 在对话中如果发现它违反约束，立刻打断，明确说“你违反了 XX 约束，请先回滚，再重新开始”。不要让它在错误路径上继续跑。
我用过这个策略后，违反频率下降得很快。本质上，模板和对话要形成一种“双保险”，模板负责预置规则，对话负责即时纠偏。
5.2 模板在大型项目里失效的原因
还有一个常见现象：同一个模板在小项目里效果极好，到了大型 monorepo 里就明显变弱。这不是模板写错了，而是大型项目的信息噪声太大。Claude Code 虽然会索引代码库，但当你给它一个模板让它扫描全部代码时，它很容易被无关代码带偏。
我的经验是：大型项目里要主动把“范围”写进模板。不要写“检查这个模块的所有问题”，而要写“只检查由 src/services/order 目录下的变更引起的潜在风险”。范围越窄，上下文里噪声越少，约束的效力越强。这也是为什么我在设计模板时一直强调“可组合”：一个通用模板加上一个范围参数，才能适配大型库。
5.3 千万不要掉进“模板越多越好”的陷阱
第二十八条实战经验：模板库越大，维护成本越高，坏规则传染越快。你会发现每个模板里都有几行“当时为了解决某个特殊问题”加的约束，但这些约束在大部分任务里根本用不上，反而破坏了模板的通用性。
所以我现在一个季度会做一次清理，把那些覆盖场景过窄的规则踢出去，统一挪到专项说明文档里，并在有需要时再临时附加。一个模板最好保持在 200 到 600 字左右。短于 200 字，约束往往不够；长于 600 字，模型容易漏焦点。
5.4 团队共享模板时的权限与同步问题
如果模板库是放在个人项目里，随便怎么折腾都行。但一旦拉进团队仓储，就涉及“谁的模板优先”的问题。我的建议是：模板库里只放通用规则，不放针对任何个人习惯的偏好条款。有人喜欢让 Claude 用特定测试框架，有人喜欢让它输出中文注释，这些偏好一律不该进公共模板。公共模板的价值是统一“跟 AI 协作的基础纪律”，不是统一“代码风格审美”。
团队还要约定一个同步流程：每次调整模板必须附带变更说明，说明里写清楚“这行约束解决了哪个实际事故”。这能防止模板库变成长期不维护的僵尸文档。
5.5 一个简易排查速查表
| 现象 | 可能原因 | 解决动作 |
|---|---|---|
| 输出越来越偏 | 模板过长，注意力分散 | 精简模板，把关键约束前移 |
| 完全不遵守禁止项 | 约束被淹没在描述里 | 改成独立列表并显式强调 |
| 大型项目里效果下降 | 任务范围过大 | 范围参数尽可能缩小到具体文件或模块 |
| 模板加了很多但没效果 | 规则针对性差 | 做减法，只保留跟任务强相关的条款 |
| 团队成员各改各的模板 | 缺少统一维护机制 | 收归公共仓库并配置变更说明 |
这个表几乎覆盖了我使用模板过程中遇到的绝大多数问题。如果你也正在经历类似的困扰，对照着排查，大概率能在十分钟内找到问题根源。
6. 模板演进的下一步方向
这个项目当下做得最多的，是围绕“模板跟项目记忆的联动”做实验。过去模板是静态文件，对每个仓库一视同仁。实际运行中我发现，最有价值的模板应该是能引用项目特定经验的。比如某个仓库历史上有过数据库迁移的线上事故，那么在设计迁移类模板时，就可以把“必须生成回滚脚本”自动注入进去。
理想形态是：一个基础模板库负责通用行为，一层项目级配置负责注入本地规则，两者叠加之后产出真正适配当前代码库的指令体系。这套结构做下来之后，Claude Code 在这些项目里的行为会逐步逼近“一个熟悉这个代码库生态的老工程师”的水平。
另外我还建议尝试把模板与自动化流水线结合起来。比如在 Merge Request 触发时自动调用 code-review 模板，让 Claude 作为机器 review 的一环先于人工介入。这个场景下模板的价值会从“帮我写代码”延伸到“帮我守质量门禁”，适用面一下就变宽了。这个方向后续如果能稳定跑通，我会把结果同步到项目里。
最后分享一个个人认为最重要的使用心法：模板不是给 Claude 看的，是给未来的自己看的。每一次模板的调整，本质上都是把一次踩坑的经验固化成结构。你在写模板时花的每一分钟，都会在之后几十次任务里悄悄省回来。如果你也准备整理自己的 Claude Code 模板，建议从一个你最近吃过大亏的任务场景开始，把这个教训写进模板第一条约束。我试过，这是这套工具链里回报率最高的一步。
