维护 claude-code-templates 这个仓库一年多之后我越来越确信一件事对于 Claude Code 这类编程代理模板不是可有可无的装饰而是把它从“好用的对话助手”变成“能稳定交付结果的工作流引擎”的钥匙。这个仓库最初只是我本地一堆零散的 markdown 文件后来逐步整理成一套可复用的模板集覆盖代码审查、测试生成、重构迁移、文档同步等高频开发场景。如果你已经上手过 Claude Code觉得它“会用但不够稳”或者在团队里推 AI 编程时发现每个人用出来的效果天差地别这篇文章会讲清楚模板到底应该怎么设计、怎么存放、怎么演进。1. 空手用 Claude Code 的困境我为什么从零攒这套模板1.1 会话漂移模型会忘记几轮之前说好的约定我先说一个大部分人第一次用 Claude Code 都会遇到的场景。你让它帮你写一个新模块一开始给了很详细的要求“错误处理统一用 Result 类型不要直接 throw”前两轮它执行得很好。结果对话进行到二十分钟你开始让它改别的文件它突然就写了一个throw new Error出来。你质问它为什么违反约定它很诚恳地道歉然后改掉。但再过几轮同样的问题又出现。这不是模型“笨”而是上下文窗口中只有一部分信息始终处于激活状态。对话越长早期约束的权重越低。我们的口头约定只存在于这个会话的气泡里气泡一长边缘就模糊。这个问题靠“每次都重新说一遍要求”能缓解但治标不治本尤其当你在同一个项目里连续工作一整天时重复描述要求本身就成了巨大的精力消耗。1.2 团队协作时效果方差大得吓人第二个让我下决心整理模板的契机是我所在的团队。最开始我建议同事们都用 Claude Code 辅助写代码结果反馈两极分化有人觉得是“神器”有人觉得“还不如自己写”。我把两边的对话记录对比了一下发现差距根本不在于模型能力而在于使用者给出的上下文质量。会用的人会在对话开头就扔进项目的 CLAUDE.md、相关模块的接口文档然后精确说明输入输出。不会用的人只会说“帮我改一下这个文件让它更好”。更棘手的是即使是同一个“帮我看代码”的指令A 同事期望的是找 bugB 同事期望的是评估架构C 同事期望的是补注释。指令本身没有规范输出自然各说各话。我当时意识到如果能把“好的提问方式”沉淀成一套可复现的模板再把这套模板放进仓库里统一管理那么团队里每个人调用 Claude Code 时的基础线就能被拉齐。这就是 claude-code-templates 的起点。所以这个仓库从第一天起就不只是给我自己用的而是为了让团队的协作经验能被固化下来。1.3 模板化的收益不是限制工具而是统一口径有人会担心把 Claude Code 的用法模板化会让它变得死板。我的实际感受恰恰相反。好的模板是在约束之下留出自由度它限制了“角色定位”“输出格式”“验收标准”这些容易跑偏的部分但给具体执行方案留了很大的想象空间。模型被约束得越清楚发挥得越稳定。就像写代码要有 lint 规则一样AI 编程也需要一套“提示词层面的 lint 规则”。模板让模型的行为方差变小让结果中的意外只出现在真正需要创造力的地方而不是出现在“用户说的是 A、AI 理解成 B”这种低级偏差上。2. 模板仓库的骨架四层分离的设计思路2.1 目录结构总览我设计 claude-code-templates 的第一步是定目录结构。一开始我只是把所有 markdown 文件堆在一个文件夹里很快发现不行模板一多“代码审查”这种模板有七八个变体连我自己都会搞混更别说团队协作。后来我参考了代码分层的思想把模板分成四个层面。claude-code-templates/ ├── memories/ │ ├── global.CLAUDE.md │ └── project.CLAUDE.md ├── prompts/ │ ├── code-review.md │ ├── test-generation.md │ ├── refactoring-migration.md │ └── documentation-sync.md ├── agents/ │ ├── review-specialist.md │ ├── test-designer.md │ └── migration-planner.md ├── hooks/ │ ├── pre-tool-use-check.sh │ └── post-stop-commit.sh ├── commands/ │ ├── /review.md │ ├── /test.md │ └── /migrate.md └── scripts/ └── render_template.py四个层面的分工也很明确memories 是长期记忆层prompts 是任务技能层agents 是角色分工层hooks 是自动触发的保障层。2.2 记忆层CLAUDE.md 的写法要点我见过很多人把 CLAUDE.md 写成了一篇散文或者干脆写了一堆放之四海而皆准的废话比如“请写出清晰、可维护的代码”“请保证高质量”。这种写法可以说是浪费了它最宝贵的价值。CLAUDE.md 的功能是给 Claude Code 注入项目专属的长期上下文它的内容越具体、越可验证效果越好。以我仓库里的一份前端项目 CLAUDE.md 为例## 项目规范 - 类型定义统一放 src/types.ts禁止在组件内内联复杂类型 - 所有异步请求必须走 src/api/client.ts不直接使用 fetch - 新增状态管理时必须经过全局 Store 目录不引入新依赖库 - 组件样式优先使用项目自带 design system 的类名不写内联 style - 测试文件与被测文件同目录命名 *.test.ts每条规则都指到了一个具体文件产生了一个明确的动作。模型不需要“理解精神”直接照做就好。这就像给新人发了一份带路标的操作规程而不是一句“你要努力工作”。另一个容易被忽略的点CLAUDE.md 不必追求大而全只写那些“不做就一定会出事”的规则。规则太多每条的注意力权重都会被稀释。如果二十条规则之间还有隐含冲突模型就会经常陷入两难。2.3 技能层提示词的“角色—上下文—任务—验收”四要素prompts 目录下放的是每个高频任务的核心提示词模板。我发现好的任务级模板都有一个共同的骨架我把它们提炼成四个要素。角色明确 AI 以什么身份执行任务比如“资深后端工程师”“只关注安全问题的审计员”。这一步在特定领域特别有用。上下文给出必要的背景包括要处理的文件目标、相关约束、已知条件。这是模板的“输入口”。任务动作要具体可执行。避免“优化一下”这类模糊动词尽量换成“找出变量名与职责不符的代码并列出行号”。验收定义输出形式和判断标准可以要求“只输出表格”“必须给出证据”“不得超出本次涉及范围”。我每次写新模板的时候都会按这四个要素检查一遍。缺了哪个环节输出就容易跑偏。3. 三套核心模板解剖审查、测试与迁移3.1 代码审查模板从“看一眼”到“查档案”代码审查是我用到最多的一类模板。最开始我用 Claude Code 做代码审查的时候往往直接说“帮我 review 这段代码”它的回答很流畅但也很浅经常给出一堆“可读性有待提高”“建议增强健壮性”这种无法落地的建议。后来我把审查过程分成两步先收集档案再逐项排查。我仓库里的代码审查模板长这样你现在是一名一线开发团队中做 code review 的资深工程师。 审查我指定的文件之前必须先读取该文件涉及的调用关系、依赖定义和测试文件。 审查输出必须按以下五部分组织每部分用表格呈现 1. 变更影响面本次改动会影响哪些模块有哪些副作用 2. 隐藏缺陷重点排查并发、异常处理、资源释放、边界条件 3. 一致性是否符合项目 CLAUDE.md 中定义的规范 4. 安全性输入校验、权限校验SQL/命令注入风险 5. 建议分级必须修改 / 建议修改 / 可选优化 每条发现必须标注文件路径和行号并给出可直接落地的修改示例。 禁止输出“代码质量有待提高”这类空话。模板生效的关键在最后两行。要求“标注文件路径和行号”直接消灭了空泛的建议“禁止空话”则从输出层面做了硬性过滤。我在实测中对比过用模板的版本和不用的版本相比真正能定位问题的发现数大约是后者的三倍。3.2 测试生成模板围绕边界条件自动铺设用例写测试是 Claude Code 很擅长、但经常做不完整的一件事。如果你只说“给这个函数补测试”它大概率会很快生成一组 happy path 用例边界条件和异常分支基本漏光。问题在于模型默认情况下倾向于“生成看起来不错的代码”而不是“穷举可能的失败场景”。所以我的测试生成模板里专门加了一个“失败清单”步骤你是测试设计专家。给指定函数设计测试用例时必须先穷举以下清单 - 正常输入的最小值、最大值、典型值 - 空值、null、undefined、空数组 - 超过类型范围的输入 - 并发调用时的竞态条件 - I/O 失败、超时、磁盘满 - 依赖服务返回错误码 只有清单中的每一项都落到了具体测试用例里你才可以输出代码。 测试代码必须用项目中已有测试框架不允许新增依赖。模板的作用其实就是强制模型走一遍“测试设计 checklist”。我用这个模板生成了一个工具函数的测试集覆盖了大概八十多个用例。后来项目跑回归的时候有两个用例真的拦住了线上才暴露的问题。那次之后我把测试模板升级成了仓库里的旗舰模板。3.3 重构迁移模板给旧代码换心脏的安全网重构迁移是最容易出乱子的场景。模型一旦开始动一个存在了四五年的旧模块很有可能会把原本有意为之的怪写法当成错误“修正”掉。所以迁移类模板的核心玩法不是“敢动”而是“先立规矩再动刀”。我写的一版更是强调“先出迁移影响面分析等用户确认后才能动手”。模板的关键段落如下在修改任何代码前先产出一份迁移计划包括 - 现状文件清单每个文件的大小、依赖数量、外部调用方 - 目标架构映射每个现状模块对应到新架构的哪个位置 - 风险分级高风险的放在最前面标注原因 - 回滚方案如果迁移到一半失败如何恢复到原状态 计划得到用户明确确认之前禁止修改任何代码文件。 迁移过程中每改完一个文件必须运行对应测试并提供测试通过的证据。为什么我要加“得到确认才能动手”这句因为模型在面对“帮我重构”这种大任务时经常会高估自己的判断直接一口气改十几个文件。等用户反应过来已经很难定位哪些改动是有意的、哪些是误伤。模板在这里起到的效果是设置了一个安全闸门让每一步都有显式的检查和确认点。4. 让模板真正生效CLAUDE.md、子代理与 Hooks 的组合打法4.1 自定义命令把常用模板变成斜杠指令有了模板文件之后我遇到的第一个问题是怎么方便地调用它。每次复制粘贴模板主体进对话依然很原始。Claude Code 的自定义命令机制解决了这个问题。在.claude/commands/目录下放一个带斜杠命令名称的 markdown 文件就可以在对话里用/命令名直接调起对应模板。比如我把审查模板放进.claude/commands/review.md之后每次只要输入/review src/utils/token.ts模板内容就会自动加载后面的文件路径会被当作参数传入。这大大降低了我写提示词的心理门槛也让团队里其他人更容易上手——他们不需要知道自己该怎么“写好提示词”只要知道用哪个命令就行。命令文件里还可以用$ARGUMENTS接收参数我把这个能力用在了“指定审查深度”“指定要跳过的文件”等场景。4.2 子代理把大而全的模板拆成专业顾问模板越写越多之后我又发现了一个新问题把它塞给同一个模型角色切换太频繁会不稳定。比如我在一个会话里先让它做代码审查紧接着又让它生成测试它容易把前面的“资深审查者”语气带到后面的测试设计里去。在 Claude Code 里可以用子代理来解决这个角色冲突的问题。我给每个高频任务定义了一个专门的子代理每个子代理有自己的名称、职责描述和工具权限。在设计上一个子代理就对应一个稳定的专业角色。name: code_reviewer description: 专门做代码审查只输出定位到文件路径和行号的问题 tool: - read - grep - glob - bash 你是一个只负责代码审查的资深工程师。你会严格遵守以下规则 1. 着手审查前必须读取被审查文件的调用链 2. 每条问题必须标注文件路径和行号 3. 所有输出按“必须修改 / 建议修改 / 可选优化”分类 4. 你不负责修复代码只负责给出审查结论把任务拆给子代理之后主对话只需要调度它们干活就行。这就像你带了一个团队而不是把一个全栈工程师绑在同一个岗位上。对于稍有规模的代码库这个设计带来的稳定性提升非常明显。4.3 Hooks让模板在关键时刻自动触发模板也可以套在事件上。Claude Code 的 Hooks 可以在工具调用前后、对话结束等时机触发自定义脚本。我把其中一些规则自动化之后就再也不依赖自己逐个手动传递模板了。一个很实用的配置是在工具调用前检查“是否触碰了不该碰的文件”。{ hooks: [ { matcher: PreToolUse, hook: /path/to/pre-tool-use-check.sh, commands: [Write, Edit] } ] }脚本里可以定义“受保护路径”清单。如果模型执行写操作的对象是src/generated/或者config/production.yaml这类文件就直接拦截并抛出一条说明。这种做法相当于把模板里“不要修改未授权的文件”这条约束从软性提示变成了硬性门禁。我同时也在Stop事件上挂了一个钩子事件触发后自动运行测试套件。这算是给模型收尾加了一道自动检查。Hooks 的定位是给模板一个执行时机让好的规则不只是存在于大脑中而是嵌在流程里。5. 模板失灵的三种典型情况与修复过程5.1 冲突式约束当模板自己打架我最早踩过的一个坑是模板里的约束互相矛盾。有一版 CLAUDE.md 我同时写了“保持代码简洁避免冗余”和“每个函数必须补全详细注释”。看起来好像没问题但碰上复杂业务函数时模型就会陷入两难注释写细了显得代码冗余代码精简了又不够注释量。它的具体表现就是在两个约束之间摇摆输出时而详细时而精简毫无规律。修复办法是给规则分优先级并且在规则里给出边界- 所有规则中「代码简洁」优先级最高 - 函数注释只要求写清楚参数含义和返回值约定禁止抄代码行 - 复杂逻辑超过 20 行时注释优先详细其余情况注释从简模型在遇到冲突时需要有明确的裁决依据。如果模板设计者自己都没想到规则之间会冲突那结果只能靠模型自由发挥。5.2 上下文缺失模板引用了会话里不存在的信息另一种常见的失败是模板里提到了某个文件但会话当时并没有读取那个文件。模型不会像浏览器一样自动去打开所有相关页面它很容易在讨论一个接口时依赖自己对文件内容的猜测去生成回答。我第一次用重构模板时就遇到了这个情况。模板要求它给出“受影响文件清单”它直接写了一个不存在的文件名上来原因是它根本没读过源文件只是在凭经验推断。修复方式是在模板最前面强制加一条前置动作执行任何任务前先用 grep / glob 确认相关文件是否存在。 所有涉及的文件路径必须先读取再进入分析。这条规则看起来简单但对模型来说却是一个“强制加载上下文”的开关。加了它之后幻觉文件名的出现率直线下降。5.3 模板过长注意力被稀释最后一个坑是我们自己造成的。随着模板越写越全一些关键模板的篇幅开始膨胀代码审查模板一度写到了三百多行里面塞了很多历史上碰到过的特殊场景。结果我发现模型在长模板下面反而表现变差“必须修改级别”的发现率反而有点下降。原因不难理解上下文窗口中信息过载后模型会顾此失彼前面说过的重要要求被后面的细节挤占。后来我把长模板按职责拆分成多个子代理每个子代理只专注一个细分环节。审查模板拆成了“架构影响检查”“实现细节检查”“安全漏洞检查”三个代理每个文件都控制在六十行以内。拆分后效果立刻不一样了。与其训练一个什么都会但什么都不精的模型不如给它几个专职同事。最后说一点维护 claude-code-templates 的实际体会模板库不是一劳永逸的工程它像一个活的协议得跟着实际踩坑不断演进。我给自己定了一个硬规矩每次让 Claude Code 干砸一件事都要把它失败的原因写回对应模板。有一次它在迁移时误改了配置文件我就把那个配置目录加进了“禁止修改清单”还有一次它在生成测试时编造了一个 mock 数据我把“禁止编造运行时不存在的对象”写进了测试设计模板。慢慢地这套模板就成了团队最真实的代码纪律沉淀池比任何文档都有执行力。如果你准备开始建自己的模板库我的建议是小步快跑先挑一个你每周都会重复的任务例如代码审查写一份二十行左右的模板跑通之后再加第二个场景。不要想着第一天就建出一个大而全的体系。工具会更新模型会升级但是“把好的协作方式固化成模板”这件事永远不会过时。