用Claude Code一段时间后你会发现真正拉开效率差距的不是模型本身而是你喂给它的那套模板。很多人把claude-code当成一个简单的命令行问答工具随便丢一句“帮我看看这段代码”就用结果输出质量忽上忽下上下文一长就开始胡说。其实问题不在模型在于你根本没有给它一套稳定、可复用的工作协议。而claude-code-templates本质上就是给AI编程代理设计的一套“职业训练手册”——把你自己反复踩坑后才形成的编码规范、审查要点、重构策略沉淀成一段段可以被反复调用的指令模板。这篇文章我就聊聊我自己的模板体系是怎么搭的里面踩过哪些坑哪些写法真正能提升输出质量以及模板多了之后怎么管理才不乱。1. 为什么Claude Code必须配模板没有模板的AI助手等于裸奔先说个我自己的真实对比。最早用Claude Code时我习惯用自然语言临时指挥它“看看这个函数有什么问题”。它也能干活但每次都要我现场补充一堆背景信息“这是后端服务”“我们用的是Python 3.11”“数据库是PostgreSQL”“要关注并发安全问题”。同一个项目我每天要重复输入十几次这样的上下文烦到崩溃。更麻烦的是一旦需求描述不够精确它给出的建议经常泛泛而谈比如“建议加强错误处理”——这种话谁不会说真正的代码评审需要的是“第37行这个字典查询没有默认值如果key不存在会直接抛KeyError应该用.get()或者先做成员检查”而不是一句正确的废话。模板解决的就是这个“稳定交付质量”的问题。它的核心机制很简单把你对任务的理解、执行步骤、输出格式、甚至语气和行文风格预先写成一套标准指令。每次调用时只替换其中少数变量文件路径、任务描述剩下的事情模型会按你的约定来办。相当于你给每个高频任务做了一张“操作卡片”上面写着“见到这个场景按这个流程走输出这个格式”。具体到claude-code场景里模板的价值体现在三个层面。第一层是上下文压缩模板能替代大量重复的背景说明减少对话轮数让模型更早进入实际工作状态。第二层是输出一致性有了固定结构模型的回复不会跳跃性发散代码风格、注释语言、报告格式都能保持统一。第三层是隐性知识与团队复用一个老手踩坑总结出来的审查清单通过模板传给新人效果比十次口头指导都好。我团队里现在所有成员都在用同一套模板基础代码评审的口径基本一致这就是模板带来的工程红利。但这里有个关键前提模板不是写得越多越好也不是越长越好。模板是“给模型的约束”约束过多会让模型束手束脚约束过少又回到裸奔状态。我见过有人把模板写成一万字的大全塞进上下文后模型光记你的规矩就占了大量额度实际干活的能力反而下降。所以设计模板的第一原则是只约束“输出边界和关键检查项”不约束“具体实现过程”。你要的是它按你的验收标准交付不是控制它的每一行代码。2. 模板体系的整体设计先分好类再写内容现在很多讨论都集中在“怎么写单条prompt”上但真正让模板发挥作用的其实是体系。我的经验是先把模板按使用频率和复杂度分成四层最底下是全局行为基线中间是高频任务模板上面是场景专用模板最顶上是即时一次性模板。这个分层不是拍脑袋定的而是对应着你在实际编码里碰到不同类型的请求时需要的干预粒度完全不同。2.1 第一层全局行为基线CLAUDE.md全局行为基线是Claude Code最底层的约束通常放在项目的CLAUDE.md里模型每次进入项目都会自动加载。这一层管的是“你在我的项目里默认应该怎么表现”。比如项目用什么语言和框架、代码风格偏好函数命名用snake_case还是camelCase、默认要遵守的错误处理规范、文件组织约定、注释语言用什么、测试怎么写。这些不是某个具体任务的约束而是所有任务共用的背景知识。我写过一版比较实用的CLAUDE.md核心只有几条代码必须匹配项目现有风格不引入新范式任何对外接口改动必须同步修改调用方所有新的错误分支必须有日志和可观测性埋点禁止修改requirements.txt之外的依赖版本。这些条目不多但每一条背后都有我真实踩过的坑。比如“不引入新范式”这条就是因为有次模型给我在Python项目里引入了dataclass虽然功能没错但和全项目手写类的方式格格不入后来者读代码时会产生割裂感。写全局基线时要特别注意“可用性”。基线不是面试题不是越详细越好。每一条规则都应该是可验证的比如“遵循PEP8”这种可验证性就很差什么算遵循但“函数内超过20行就拆分成多个私有函数”是可验证的。可验证的规则模型才能落实到代码里不可验证的规则只会消耗上下文。另外全局基线应该靠“否定句”来收敛边界而不是靠“肯定句”来发散可能性。多说“不要用X”比说“你可以用Y也可以用Z”更清晰。2.2 第二层高频任务模板第二层是高频任务模板也就是我这次整理claude-code-templates时最花心思的部分。这层模板覆盖的是每天都会用到的固定场景典型的有代码审查code review、bug定位与修复、单元测试生成、重构、新功能实现、文档编写。我是按“任务动作”来分类的而不按“项目模块”来分类因为同一个动作在不同模块里执行时行为跨度是可控的模板改动量小。每个高频任务模板内部其实是三段式的结构任务输入、执行流程、输出格式。任务输入告诉你需要提供什么变量执行流程告诉模型先做什么、再做什么、最后做什么输出格式规定回复的骨架。举个例子我的代码审查模板就是这样定义的第一步要求列出代码上下文文件路径、改动范围、审查焦点第二步按“正确性、性能、可读性、安全性、可测性”五个维度逐项检查第三步输出审查报告报告每个问题必须标注“严重级别、证据定位、修改建议”。有了这个三段式模型不会把审查写成泛泛的读后感。设计高频模板时还有一个容易被忽略的问题这些模板应该尽量“不依赖具体项目技术栈”而是保持通用性。这样才能做到换项目不换模板。具体项目的技术细节交给CLAUDE.md去管模板只管“审查动作本身”。这样做的另一个好处是模板的维护成本大幅下降你不需要因为项目换了框架就去改十几个模板。2.3 第三层场景专用模板与一次性模板第三层是场景专用模板比如“代码迁移到新框架”、“性能优化分析”、“API设计评审”、“数据库索引评审”。这类模板使用频率比高频模板低但复杂度更高需要注入大量领域知识。例如“代码迁移”模板里除了通用的执行流程我还会内置一个“兼容性检查清单”包括保持对外行为不变、检查导入路径、处理废弃API、保证日志语义等。第四层则是即时一次性模板通常是临时想到的需求比如“帮我对比一下ORM方案A和方案B”。这种模板不需要严格设计但我会保持一个“快速调用前缀”的习惯比如在指令里固定写“请先给我一个执行计划等我确认后再开始”。这个习惯能防止模型在复杂任务上一口气跑偏。四层模板之间不是孤立的。CLAUDE.md影响所有任务高频模板和场景模板则是叠加在基线上的特定执行协议一次性模板可以随时覆盖前几层的默认行为。理解了这层关系你调配模板时心里就有谱优先级排序是“一次性 场景专用 高频 全局基线”。这个排序也是排查模板冲突时的核心思路。3. 模板内容怎么打磨以代码审查模板为范例拆开给你看模板这东西光靠抽象讲没意思我直接拿我用的代码审查模板做一个完整拆解。这个模板我迭代了大概两个月现在基本稳定团队也在用。它解决了三个具体问题审查没有固定焦点、审查不深、报告过于冗长没人看。每个问题我都用具体的模板设计来对应解决。3.1 代码审查模板的完整结构先看这个模板的完整文本省略了项目特有信息你是资深代码审查者。请对给定代码进行深度审查不得只做表面评价。 审查步骤: 1. 先复述你的理解这段代码的功能目标、调用关系、数据流是什么。如果理解有歧义先提出来不要蒙头继续。 2. 按以下维度逐项检查 - 正确性: 是否存在边界条件未处理、空值/异常路径未覆盖、逻辑分支缺失? - 性能: 是否存在无意中的循环内查询、重复计算、大对象持有? - 可读性: 命名是否无歧义、函数是否过长、是否能被其他模块复用? - 安全性: 是否引入了输入校验缺失、权限校验绕过、敏感信息日志? - 可测性: 这段代码是否容易构造单测? 依赖注入是否合理? 3. 输出格式: - 总体结论: 是否建议合入 - 严重问题列表必须合入前修复 - 建议优化列表可以后续处理 - 说明: 每个问题必须是具体的包含文件和行号引用代码原文说明原因。 4. 如果本次变更没有改动任何功能逻辑如纯注释/重命名明确说明“本次为纯重构不需要深入逻辑审查”然后只检查风格和一致性。你可能已经看出几个关键点。第一步“先复述理解”是非常实用的防跑偏机制。代码审查最怕模型没看懂代码就给出自信的建议让它先复述一遍等于强制它证明自己真的看懂了。一旦复述有误后续审查就不可信你可以及时打断重来。第二步的五个维度是我筛选过的实际写模板时维度不要太杂五六个足够。如果列二十个维度模型会平均用力最后每个维度都说一句空话。维度越少每个维度分到的注意力越多。这里也体现了模板的“约束要精确到行为”原则我不说“注意性能问题”我说“是否存在循环内查询”这才能被精确执行。3.2 为什么这样写围绕“检查和输出”做约束模板设计的精髓在于约束什么、不约束什么。我这份审查模板里约束的是“审查时检查哪些维度”以及“输出报告的格式”。不约束的是“用什么样的语气评价代码”、不约束“必须给出代码补丁”、不约束“必须使用某个英文术语”。这些不约束的点一旦被约束反而会让报告变得僵硬。比较典型的一个争议点要不要让模板强制要求模型输出“修改后的代码”我的答案是在审查模板里不要求在修复模板里才要求。审查和修复是两件事混在一起模型就很难纯粹地去“挑刺”它会产生路径依赖总想着自己怎么改而不是帮你看当前的代码好不好。审查就做审查修复就做修复各干各的输出质量都更高。还有一个细节模板第三步要求报告必须引用代码原文并标注行号。很多工具生成的审查报告最大的毛病就是“正确但无用”比如“第x行附近存在潜在问题”——你到底指哪一句强制引用原文后模型必须定位到准确表达式而不是围绕一个模糊的范围打转。这个引用原文的机制对压住模型的“正确废话”特别好使。3.3 测试生成模板与重构模板的要点代码审查模板只是其中一个例子。测试生成模板我同样迭代过多次其中最大的坑是“模型爱写快乐路径”。你让它给函数生成单测它连异常路径都不测就跑完了。所以我的测试模板里强制规定必须先列出“正常路径、边界值、异常路径、并发/时序如果适用”四类用例然后再逐一实现。这一步前置规划能逼着模型把测试全集想全而不是想到哪写到哪。重构模板则完全不一样。重构最怕“行为漂移”模型改着改着把原本的语义都改了。我的重构模板第一步固定是要求模型先总结现有代码的“外部可观察行为清单”。这个清单列出了接口调用方式、返回值的约定、异常类型、日志输出等然后重构完成后再拿着清单逐项对照验证。这相当于给重构过程加了回归围栏模型不太容易改飞。4. 模板管理实操目录组织、变量注入与动态加载模板写得再好如果管理混乱也是白搭。我现在建了一套比较完整的模板管理体系这里分享具体做法你可以直接抄作业。4.1 模板目录结构与命名规范我的claude-code-templates仓库目录大致是这样的templates/ ├── global/ │ └── CLAUDE.md # 全局基线按项目维护不放在这里 ├── tasks/ │ ├── code-review.md │ ├── bug-fix.md │ ├── unittest-generate.md │ ├── refactor.md │ ├── feature-implement.md └── scenarios/ ├── migration.md ├── performance-analysis.md ├── api-design-review.md ├── sql-index-review.md └── debugging-session.md命名上我使用小写短横线风格和文件名保持一致。关键是“一个任务一个文件”不搞那种一个大文件里塞几个模板的逻辑否则你无法通过文件名快速找到对应模板。模板文件内部包含元信息区域和正文区域元信息用来记录这个模板的适用范围、场景示例、变更历史。我通常会在文件顶部用注释块写清楚这个模板能在什么情况下用、不适用于什么场景这样半年后再看也不会忘记当初为什么写这版。目录之上还有一个关键操作模板文件本身需要纳入版本管理。我一般把整个模板目录放在一个独立的Git仓库里每次内容调整都走PR和review至少要有提交历史。这样做有两个好处一是模板变更可以像代码变更一样回溯改坏了好查原因二是团队可以用同一个仓库分发模板新人clone下来就能用比起挖聊天记录找模板靠谱太多。4.2 变量注入的三种方式模板不是死的每个模板都该留出“变量插槽”。我用三种方式做注入按灵活程度排个序第一种是字面量替换这是最简单也最直接的。比如模板里写{{file_path}}启用时手动替换成真实文件路径。合适于变量少、只自己用的场景。缺点是不适合批量操作而且每次替换都要手动处理容易出错。第二种是引用外部上下文文件。Claude Code天然支持把项目文件当作上下文所以我会让模板引用某个描述文件模型自己在项目里读取。例如“读docs/bug-report.md中的问题描述然后按模板执行”。这种方式适合变量特别多的场景不用在prompt里塞一大坨内容模型按需去读。第三种是使用Claude Code的原生参数能力比如通过--additional-notes或命令行参数动态注入。这种方式我用于“模板批量套用到多个文件”的场景比如要对5个文件做同一类重构我就循环调用每次只修改注入的文件路径。谈到批量注入我还想提一下一定不要在模板里内嵌太多需要替换的变量否则你维护模板的成本会变成维护替换脚本的成本。如果某个模板的变量超过5个我第一个反应是重新设计模板看看是不是该把通用逻辑下沉到CLAUDE.md而不是全部留在模板里。模板应该是“稳定的执行协议”变量多了会侵蚀这个协议的稳定性。4.3 动态加载怎么让模板跟着项目走模板的最终落地是在真实项目里被模型用起来。我有几个固定的习惯项目根目录的CLAUDE.md只放全局基线高频模板不放进CLAUDE.md而是放进~/.claude-code/templates或者在需要时通过--template参数指定场景模板一般和特定项目绑定我会在项目的.claude/目录下维护一个commands.md里面列出本项目常用的场景模板清单。动态加载还有一个容易踩的坑不要把模板内容复制粘贴到每次对话里因为模板一长粘贴过程中很可能被截断或引入格式错乱。更稳的做法是给模板文件建立索引每次对话只说“使用tasks/refactor.md模板目标文件是xxx”这样上下文干净模型也能明确知道要去哪里加载协议。很多人反馈模板不生效其实多半就是粘贴时格式被吃掉了。5. 常见问题与排查实录模板不生效怎么办模板系统用了一阵子后你会遇到各种怪问题。我把高频问题整理成一个排查表这些基本都是我自己踩过的坑不是凭空想象。5.1 模板“不生效”的三种情况第一类是最常见的模板加载了但模型执行时明显偏离模板约束。比如你让它按五个维度审查它还是自顾自地泛泛而谈。这种情况通常是模板和当前对话上下文发生了冲突另一种可能是模板中的指令权重不够。解决办法是把模板中最重要的约束提升到开头用“必须”“强制”这类字眼锁定同时把模板里不重要的修饰性语句删掉。模型读长文本时同样有注意力分布问题关键指令放开头是最稳的。第二类是模板被自动加载后反而拖累表现。我遇到过CLAUDE.md里某条规则和当前任务冲突模型被卡住了。比如全局基线说“不要修改公共接口”但任务要求就是改接口它就开始反复确认和犹豫。这种问题根子在于模板规则之间缺少优先级声明。我现在在CLAUDE.md里加了一条元规则“模板规则如果与用户最新明确指令冲突优先服从用户最新指令并在回复中说明冲突点。”有了这一条模型就不会被自己的规则绑架。第三类是模板内容本身没问题但上下文过长模板中关键部分被模型遗忘。这通常发生在超长会话的中后段。我的建议是如果会话预计会很长先把模板重要部分在对话中途再强调一次比如我会说“继续按代码审查模板的第2步检查性能维度”用这种“触发器指令”把模型拉回模板轨道效果很好。5.2 几个容易被忽略的模板细节问题第一个是Markdown格式对模板内容的干扰。模板里如果用了大量的Markdown标题、加粗、列表模型读取时可能会把符号当成需要“输出格式”的模仿对象导致生成内容带上多余的**。后来我把模板改成尽量使用纯文本说明偶尔用短横线列表但不再嵌套复杂样式模型输出干净了很多。第二个是模板里示例代码的副作用。如果模板中附带了一段“示例输出”模型很容易把示例当成必须重复的模板会照抄示例的文案和结构。为了避免这个问题我在模板里明确标注示例不要输出或者在示例外包裹分隔符。即便如此也尽量只放简短说明不要放完整的长示例。第三个是模板中的语言混用。团队模板里有时候中英文混杂会让模型的语气摇摆不定。我现在的约定是模板元信息用英文正文指令用中文代码相关关键词可用英文不混在一句里。这样模型输出的语言一致性也变好了。5.3 排查模板问题的实用工具与思路排查模板问题时我一般用逐步排除法。先固定baseline在不加载任何模板的干净会话里同样的任务模型表现如何。如果干净会话表现正常说明是模板压制了模型如果干净会话同样不行说明问题出在任务描述或模型能力本身不是模板的事。确认是模板问题后再用二分法逐段注释掉模板内容快速定位是哪一段规则产生了负面效果。另外我会定期检查模板的“字数与效果比”。如果一个模板超过一千字但产出还行我会怀疑是不是其中很多内容是废话。一个能跑得很好的模板通常可以压缩掉一半而不影响结果。每过一段时间把模板扔进新模型版本里重新验证一次也很重要因为模型升级后对指令的理解方式会变半年前写得好的模板可能现在就会约束过度。6. 进阶玩法让模板组合起来而不是孤立使用当你养成了模板习惯自然会遇到新瓶颈组合需求。比如一个需求既要生成单元测试又要做代码审查还要出具修改建议——这时候一个一个轮流调用模板也能完成但效率低下而且模型在不同阶段的状态会丢失。我现在的处理方式是设计“组合模板协议”在高频任务之间定义交接点。我的做法是把多个模板串成一个“流水线脚本”。比如新增功能开发我常用三步流水线先用feature-implement.md生成实现再用code-review.md审查刚生成的代码最后用unittest-generate.md补测试。每一步的输出结构都尽量能作为下一步的输入比如feature-implement模板会输出“改动文件清单和核心逻辑摘要”这个摘要正好是review模板第一步要输入的上下文。这样三步之间不会出现信息断裂。组合模板还有一个关键是“止损机制”。流水线跑起来后如果在第一步就发现实现方向错误继续往下走只会浪费更多时间。所以我在每个模板开头都加了一句“如果发现当前任务与你的理解存在重大歧义立即停止并询问澄清不要继续执行后续步骤。”这句话给每层模板都提供了一个安全阀避免模型方向错了还硬着头皮完成整套流程。想玩得更深的话还可以让模板学习和策略数据挂钩。比如把过去一周审查出的高频缺陷类型统计出来动态调整代码审查模板中维度的权重。这个我还在实验中目前的思路是每周跑一次脚本统计审查报告里严重问题的标签频率然后手动调整模板里维度出现的顺序和措辞。虽然还没做到全自动但至少让我意识到模板不应该是静态文档它和代码一样需要持续迭代和维护。7. 从模板库到工作习惯最后几句实在话我在实际操作中最深的体会是模板库的价值三分在写七分在持续用。很多人下载了一套漂亮的模板用了一次觉得“好像没多厉害”就放弃了这其实是对模板的误解。模板不是一个能让你敲一次命令就自动产出完美代码的魔法脚本它更像是一条生产线的工装夹具作用是让每次加工都在可控范围。刚开始用模板时尤其别扭因为你已经习惯了和AI随口对几句话就开干突然要按流程一步步来会觉得怎么变慢了。但只要坚持两到三周模板对稳定性的提升会非常明显地体现出来。另外一个常被问到的点“模板是不是在限制模型的创造力”我的答案是不限制创造力的方式是把创造力留给那些真正需要探索的任务而把一致性留在固定流程。对于绝大多数编码场景稳定交付远比灵光一现重要。真正需要模型发挥创造力的时候我会明确使用一个“自由探索模板”这个模板里只写一句“请用任何你擅长的方式来分析这个问题不要受常规约束目标是提出一个非平凡的方案。”这个自由模板和我的其他五个约束模板配合反而比全程自由对话让我心智更清楚。最后再分享一个小技巧把你的模板仓库提交历史当成一本成长日记。每次你调整了什么规则、为什么调整都在commit message里写清楚。几个月后回头翻一翻你会看到自己从“AI对话使用者”变成“AI工作流程设计者”的整个轨迹这个过程本身比任何单个模板都有价值。
Claude Code模板体系构建指南：从设计到实战
用Claude Code一段时间后你会发现真正拉开效率差距的不是模型本身而是你喂给它的那套模板。很多人把claude-code当成一个简单的命令行问答工具随便丢一句“帮我看看这段代码”就用结果输出质量忽上忽下上下文一长就开始胡说。其实问题不在模型在于你根本没有给它一套稳定、可复用的工作协议。而claude-code-templates本质上就是给AI编程代理设计的一套“职业训练手册”——把你自己反复踩坑后才形成的编码规范、审查要点、重构策略沉淀成一段段可以被反复调用的指令模板。这篇文章我就聊聊我自己的模板体系是怎么搭的里面踩过哪些坑哪些写法真正能提升输出质量以及模板多了之后怎么管理才不乱。1. 为什么Claude Code必须配模板没有模板的AI助手等于裸奔先说个我自己的真实对比。最早用Claude Code时我习惯用自然语言临时指挥它“看看这个函数有什么问题”。它也能干活但每次都要我现场补充一堆背景信息“这是后端服务”“我们用的是Python 3.11”“数据库是PostgreSQL”“要关注并发安全问题”。同一个项目我每天要重复输入十几次这样的上下文烦到崩溃。更麻烦的是一旦需求描述不够精确它给出的建议经常泛泛而谈比如“建议加强错误处理”——这种话谁不会说真正的代码评审需要的是“第37行这个字典查询没有默认值如果key不存在会直接抛KeyError应该用.get()或者先做成员检查”而不是一句正确的废话。模板解决的就是这个“稳定交付质量”的问题。它的核心机制很简单把你对任务的理解、执行步骤、输出格式、甚至语气和行文风格预先写成一套标准指令。每次调用时只替换其中少数变量文件路径、任务描述剩下的事情模型会按你的约定来办。相当于你给每个高频任务做了一张“操作卡片”上面写着“见到这个场景按这个流程走输出这个格式”。具体到claude-code场景里模板的价值体现在三个层面。第一层是上下文压缩模板能替代大量重复的背景说明减少对话轮数让模型更早进入实际工作状态。第二层是输出一致性有了固定结构模型的回复不会跳跃性发散代码风格、注释语言、报告格式都能保持统一。第三层是隐性知识与团队复用一个老手踩坑总结出来的审查清单通过模板传给新人效果比十次口头指导都好。我团队里现在所有成员都在用同一套模板基础代码评审的口径基本一致这就是模板带来的工程红利。但这里有个关键前提模板不是写得越多越好也不是越长越好。模板是“给模型的约束”约束过多会让模型束手束脚约束过少又回到裸奔状态。我见过有人把模板写成一万字的大全塞进上下文后模型光记你的规矩就占了大量额度实际干活的能力反而下降。所以设计模板的第一原则是只约束“输出边界和关键检查项”不约束“具体实现过程”。你要的是它按你的验收标准交付不是控制它的每一行代码。2. 模板体系的整体设计先分好类再写内容现在很多讨论都集中在“怎么写单条prompt”上但真正让模板发挥作用的其实是体系。我的经验是先把模板按使用频率和复杂度分成四层最底下是全局行为基线中间是高频任务模板上面是场景专用模板最顶上是即时一次性模板。这个分层不是拍脑袋定的而是对应着你在实际编码里碰到不同类型的请求时需要的干预粒度完全不同。2.1 第一层全局行为基线CLAUDE.md全局行为基线是Claude Code最底层的约束通常放在项目的CLAUDE.md里模型每次进入项目都会自动加载。这一层管的是“你在我的项目里默认应该怎么表现”。比如项目用什么语言和框架、代码风格偏好函数命名用snake_case还是camelCase、默认要遵守的错误处理规范、文件组织约定、注释语言用什么、测试怎么写。这些不是某个具体任务的约束而是所有任务共用的背景知识。我写过一版比较实用的CLAUDE.md核心只有几条代码必须匹配项目现有风格不引入新范式任何对外接口改动必须同步修改调用方所有新的错误分支必须有日志和可观测性埋点禁止修改requirements.txt之外的依赖版本。这些条目不多但每一条背后都有我真实踩过的坑。比如“不引入新范式”这条就是因为有次模型给我在Python项目里引入了dataclass虽然功能没错但和全项目手写类的方式格格不入后来者读代码时会产生割裂感。写全局基线时要特别注意“可用性”。基线不是面试题不是越详细越好。每一条规则都应该是可验证的比如“遵循PEP8”这种可验证性就很差什么算遵循但“函数内超过20行就拆分成多个私有函数”是可验证的。可验证的规则模型才能落实到代码里不可验证的规则只会消耗上下文。另外全局基线应该靠“否定句”来收敛边界而不是靠“肯定句”来发散可能性。多说“不要用X”比说“你可以用Y也可以用Z”更清晰。2.2 第二层高频任务模板第二层是高频任务模板也就是我这次整理claude-code-templates时最花心思的部分。这层模板覆盖的是每天都会用到的固定场景典型的有代码审查code review、bug定位与修复、单元测试生成、重构、新功能实现、文档编写。我是按“任务动作”来分类的而不按“项目模块”来分类因为同一个动作在不同模块里执行时行为跨度是可控的模板改动量小。每个高频任务模板内部其实是三段式的结构任务输入、执行流程、输出格式。任务输入告诉你需要提供什么变量执行流程告诉模型先做什么、再做什么、最后做什么输出格式规定回复的骨架。举个例子我的代码审查模板就是这样定义的第一步要求列出代码上下文文件路径、改动范围、审查焦点第二步按“正确性、性能、可读性、安全性、可测性”五个维度逐项检查第三步输出审查报告报告每个问题必须标注“严重级别、证据定位、修改建议”。有了这个三段式模型不会把审查写成泛泛的读后感。设计高频模板时还有一个容易被忽略的问题这些模板应该尽量“不依赖具体项目技术栈”而是保持通用性。这样才能做到换项目不换模板。具体项目的技术细节交给CLAUDE.md去管模板只管“审查动作本身”。这样做的另一个好处是模板的维护成本大幅下降你不需要因为项目换了框架就去改十几个模板。2.3 第三层场景专用模板与一次性模板第三层是场景专用模板比如“代码迁移到新框架”、“性能优化分析”、“API设计评审”、“数据库索引评审”。这类模板使用频率比高频模板低但复杂度更高需要注入大量领域知识。例如“代码迁移”模板里除了通用的执行流程我还会内置一个“兼容性检查清单”包括保持对外行为不变、检查导入路径、处理废弃API、保证日志语义等。第四层则是即时一次性模板通常是临时想到的需求比如“帮我对比一下ORM方案A和方案B”。这种模板不需要严格设计但我会保持一个“快速调用前缀”的习惯比如在指令里固定写“请先给我一个执行计划等我确认后再开始”。这个习惯能防止模型在复杂任务上一口气跑偏。四层模板之间不是孤立的。CLAUDE.md影响所有任务高频模板和场景模板则是叠加在基线上的特定执行协议一次性模板可以随时覆盖前几层的默认行为。理解了这层关系你调配模板时心里就有谱优先级排序是“一次性 场景专用 高频 全局基线”。这个排序也是排查模板冲突时的核心思路。3. 模板内容怎么打磨以代码审查模板为范例拆开给你看模板这东西光靠抽象讲没意思我直接拿我用的代码审查模板做一个完整拆解。这个模板我迭代了大概两个月现在基本稳定团队也在用。它解决了三个具体问题审查没有固定焦点、审查不深、报告过于冗长没人看。每个问题我都用具体的模板设计来对应解决。3.1 代码审查模板的完整结构先看这个模板的完整文本省略了项目特有信息你是资深代码审查者。请对给定代码进行深度审查不得只做表面评价。 审查步骤: 1. 先复述你的理解这段代码的功能目标、调用关系、数据流是什么。如果理解有歧义先提出来不要蒙头继续。 2. 按以下维度逐项检查 - 正确性: 是否存在边界条件未处理、空值/异常路径未覆盖、逻辑分支缺失? - 性能: 是否存在无意中的循环内查询、重复计算、大对象持有? - 可读性: 命名是否无歧义、函数是否过长、是否能被其他模块复用? - 安全性: 是否引入了输入校验缺失、权限校验绕过、敏感信息日志? - 可测性: 这段代码是否容易构造单测? 依赖注入是否合理? 3. 输出格式: - 总体结论: 是否建议合入 - 严重问题列表必须合入前修复 - 建议优化列表可以后续处理 - 说明: 每个问题必须是具体的包含文件和行号引用代码原文说明原因。 4. 如果本次变更没有改动任何功能逻辑如纯注释/重命名明确说明“本次为纯重构不需要深入逻辑审查”然后只检查风格和一致性。你可能已经看出几个关键点。第一步“先复述理解”是非常实用的防跑偏机制。代码审查最怕模型没看懂代码就给出自信的建议让它先复述一遍等于强制它证明自己真的看懂了。一旦复述有误后续审查就不可信你可以及时打断重来。第二步的五个维度是我筛选过的实际写模板时维度不要太杂五六个足够。如果列二十个维度模型会平均用力最后每个维度都说一句空话。维度越少每个维度分到的注意力越多。这里也体现了模板的“约束要精确到行为”原则我不说“注意性能问题”我说“是否存在循环内查询”这才能被精确执行。3.2 为什么这样写围绕“检查和输出”做约束模板设计的精髓在于约束什么、不约束什么。我这份审查模板里约束的是“审查时检查哪些维度”以及“输出报告的格式”。不约束的是“用什么样的语气评价代码”、不约束“必须给出代码补丁”、不约束“必须使用某个英文术语”。这些不约束的点一旦被约束反而会让报告变得僵硬。比较典型的一个争议点要不要让模板强制要求模型输出“修改后的代码”我的答案是在审查模板里不要求在修复模板里才要求。审查和修复是两件事混在一起模型就很难纯粹地去“挑刺”它会产生路径依赖总想着自己怎么改而不是帮你看当前的代码好不好。审查就做审查修复就做修复各干各的输出质量都更高。还有一个细节模板第三步要求报告必须引用代码原文并标注行号。很多工具生成的审查报告最大的毛病就是“正确但无用”比如“第x行附近存在潜在问题”——你到底指哪一句强制引用原文后模型必须定位到准确表达式而不是围绕一个模糊的范围打转。这个引用原文的机制对压住模型的“正确废话”特别好使。3.3 测试生成模板与重构模板的要点代码审查模板只是其中一个例子。测试生成模板我同样迭代过多次其中最大的坑是“模型爱写快乐路径”。你让它给函数生成单测它连异常路径都不测就跑完了。所以我的测试模板里强制规定必须先列出“正常路径、边界值、异常路径、并发/时序如果适用”四类用例然后再逐一实现。这一步前置规划能逼着模型把测试全集想全而不是想到哪写到哪。重构模板则完全不一样。重构最怕“行为漂移”模型改着改着把原本的语义都改了。我的重构模板第一步固定是要求模型先总结现有代码的“外部可观察行为清单”。这个清单列出了接口调用方式、返回值的约定、异常类型、日志输出等然后重构完成后再拿着清单逐项对照验证。这相当于给重构过程加了回归围栏模型不太容易改飞。4. 模板管理实操目录组织、变量注入与动态加载模板写得再好如果管理混乱也是白搭。我现在建了一套比较完整的模板管理体系这里分享具体做法你可以直接抄作业。4.1 模板目录结构与命名规范我的claude-code-templates仓库目录大致是这样的templates/ ├── global/ │ └── CLAUDE.md # 全局基线按项目维护不放在这里 ├── tasks/ │ ├── code-review.md │ ├── bug-fix.md │ ├── unittest-generate.md │ ├── refactor.md │ ├── feature-implement.md └── scenarios/ ├── migration.md ├── performance-analysis.md ├── api-design-review.md ├── sql-index-review.md └── debugging-session.md命名上我使用小写短横线风格和文件名保持一致。关键是“一个任务一个文件”不搞那种一个大文件里塞几个模板的逻辑否则你无法通过文件名快速找到对应模板。模板文件内部包含元信息区域和正文区域元信息用来记录这个模板的适用范围、场景示例、变更历史。我通常会在文件顶部用注释块写清楚这个模板能在什么情况下用、不适用于什么场景这样半年后再看也不会忘记当初为什么写这版。目录之上还有一个关键操作模板文件本身需要纳入版本管理。我一般把整个模板目录放在一个独立的Git仓库里每次内容调整都走PR和review至少要有提交历史。这样做有两个好处一是模板变更可以像代码变更一样回溯改坏了好查原因二是团队可以用同一个仓库分发模板新人clone下来就能用比起挖聊天记录找模板靠谱太多。4.2 变量注入的三种方式模板不是死的每个模板都该留出“变量插槽”。我用三种方式做注入按灵活程度排个序第一种是字面量替换这是最简单也最直接的。比如模板里写{{file_path}}启用时手动替换成真实文件路径。合适于变量少、只自己用的场景。缺点是不适合批量操作而且每次替换都要手动处理容易出错。第二种是引用外部上下文文件。Claude Code天然支持把项目文件当作上下文所以我会让模板引用某个描述文件模型自己在项目里读取。例如“读docs/bug-report.md中的问题描述然后按模板执行”。这种方式适合变量特别多的场景不用在prompt里塞一大坨内容模型按需去读。第三种是使用Claude Code的原生参数能力比如通过--additional-notes或命令行参数动态注入。这种方式我用于“模板批量套用到多个文件”的场景比如要对5个文件做同一类重构我就循环调用每次只修改注入的文件路径。谈到批量注入我还想提一下一定不要在模板里内嵌太多需要替换的变量否则你维护模板的成本会变成维护替换脚本的成本。如果某个模板的变量超过5个我第一个反应是重新设计模板看看是不是该把通用逻辑下沉到CLAUDE.md而不是全部留在模板里。模板应该是“稳定的执行协议”变量多了会侵蚀这个协议的稳定性。4.3 动态加载怎么让模板跟着项目走模板的最终落地是在真实项目里被模型用起来。我有几个固定的习惯项目根目录的CLAUDE.md只放全局基线高频模板不放进CLAUDE.md而是放进~/.claude-code/templates或者在需要时通过--template参数指定场景模板一般和特定项目绑定我会在项目的.claude/目录下维护一个commands.md里面列出本项目常用的场景模板清单。动态加载还有一个容易踩的坑不要把模板内容复制粘贴到每次对话里因为模板一长粘贴过程中很可能被截断或引入格式错乱。更稳的做法是给模板文件建立索引每次对话只说“使用tasks/refactor.md模板目标文件是xxx”这样上下文干净模型也能明确知道要去哪里加载协议。很多人反馈模板不生效其实多半就是粘贴时格式被吃掉了。5. 常见问题与排查实录模板不生效怎么办模板系统用了一阵子后你会遇到各种怪问题。我把高频问题整理成一个排查表这些基本都是我自己踩过的坑不是凭空想象。5.1 模板“不生效”的三种情况第一类是最常见的模板加载了但模型执行时明显偏离模板约束。比如你让它按五个维度审查它还是自顾自地泛泛而谈。这种情况通常是模板和当前对话上下文发生了冲突另一种可能是模板中的指令权重不够。解决办法是把模板中最重要的约束提升到开头用“必须”“强制”这类字眼锁定同时把模板里不重要的修饰性语句删掉。模型读长文本时同样有注意力分布问题关键指令放开头是最稳的。第二类是模板被自动加载后反而拖累表现。我遇到过CLAUDE.md里某条规则和当前任务冲突模型被卡住了。比如全局基线说“不要修改公共接口”但任务要求就是改接口它就开始反复确认和犹豫。这种问题根子在于模板规则之间缺少优先级声明。我现在在CLAUDE.md里加了一条元规则“模板规则如果与用户最新明确指令冲突优先服从用户最新指令并在回复中说明冲突点。”有了这一条模型就不会被自己的规则绑架。第三类是模板内容本身没问题但上下文过长模板中关键部分被模型遗忘。这通常发生在超长会话的中后段。我的建议是如果会话预计会很长先把模板重要部分在对话中途再强调一次比如我会说“继续按代码审查模板的第2步检查性能维度”用这种“触发器指令”把模型拉回模板轨道效果很好。5.2 几个容易被忽略的模板细节问题第一个是Markdown格式对模板内容的干扰。模板里如果用了大量的Markdown标题、加粗、列表模型读取时可能会把符号当成需要“输出格式”的模仿对象导致生成内容带上多余的**。后来我把模板改成尽量使用纯文本说明偶尔用短横线列表但不再嵌套复杂样式模型输出干净了很多。第二个是模板里示例代码的副作用。如果模板中附带了一段“示例输出”模型很容易把示例当成必须重复的模板会照抄示例的文案和结构。为了避免这个问题我在模板里明确标注示例不要输出或者在示例外包裹分隔符。即便如此也尽量只放简短说明不要放完整的长示例。第三个是模板中的语言混用。团队模板里有时候中英文混杂会让模型的语气摇摆不定。我现在的约定是模板元信息用英文正文指令用中文代码相关关键词可用英文不混在一句里。这样模型输出的语言一致性也变好了。5.3 排查模板问题的实用工具与思路排查模板问题时我一般用逐步排除法。先固定baseline在不加载任何模板的干净会话里同样的任务模型表现如何。如果干净会话表现正常说明是模板压制了模型如果干净会话同样不行说明问题出在任务描述或模型能力本身不是模板的事。确认是模板问题后再用二分法逐段注释掉模板内容快速定位是哪一段规则产生了负面效果。另外我会定期检查模板的“字数与效果比”。如果一个模板超过一千字但产出还行我会怀疑是不是其中很多内容是废话。一个能跑得很好的模板通常可以压缩掉一半而不影响结果。每过一段时间把模板扔进新模型版本里重新验证一次也很重要因为模型升级后对指令的理解方式会变半年前写得好的模板可能现在就会约束过度。6. 进阶玩法让模板组合起来而不是孤立使用当你养成了模板习惯自然会遇到新瓶颈组合需求。比如一个需求既要生成单元测试又要做代码审查还要出具修改建议——这时候一个一个轮流调用模板也能完成但效率低下而且模型在不同阶段的状态会丢失。我现在的处理方式是设计“组合模板协议”在高频任务之间定义交接点。我的做法是把多个模板串成一个“流水线脚本”。比如新增功能开发我常用三步流水线先用feature-implement.md生成实现再用code-review.md审查刚生成的代码最后用unittest-generate.md补测试。每一步的输出结构都尽量能作为下一步的输入比如feature-implement模板会输出“改动文件清单和核心逻辑摘要”这个摘要正好是review模板第一步要输入的上下文。这样三步之间不会出现信息断裂。组合模板还有一个关键是“止损机制”。流水线跑起来后如果在第一步就发现实现方向错误继续往下走只会浪费更多时间。所以我在每个模板开头都加了一句“如果发现当前任务与你的理解存在重大歧义立即停止并询问澄清不要继续执行后续步骤。”这句话给每层模板都提供了一个安全阀避免模型方向错了还硬着头皮完成整套流程。想玩得更深的话还可以让模板学习和策略数据挂钩。比如把过去一周审查出的高频缺陷类型统计出来动态调整代码审查模板中维度的权重。这个我还在实验中目前的思路是每周跑一次脚本统计审查报告里严重问题的标签频率然后手动调整模板里维度出现的顺序和措辞。虽然还没做到全自动但至少让我意识到模板不应该是静态文档它和代码一样需要持续迭代和维护。7. 从模板库到工作习惯最后几句实在话我在实际操作中最深的体会是模板库的价值三分在写七分在持续用。很多人下载了一套漂亮的模板用了一次觉得“好像没多厉害”就放弃了这其实是对模板的误解。模板不是一个能让你敲一次命令就自动产出完美代码的魔法脚本它更像是一条生产线的工装夹具作用是让每次加工都在可控范围。刚开始用模板时尤其别扭因为你已经习惯了和AI随口对几句话就开干突然要按流程一步步来会觉得怎么变慢了。但只要坚持两到三周模板对稳定性的提升会非常明显地体现出来。另外一个常被问到的点“模板是不是在限制模型的创造力”我的答案是不限制创造力的方式是把创造力留给那些真正需要探索的任务而把一致性留在固定流程。对于绝大多数编码场景稳定交付远比灵光一现重要。真正需要模型发挥创造力的时候我会明确使用一个“自由探索模板”这个模板里只写一句“请用任何你擅长的方式来分析这个问题不要受常规约束目标是提出一个非平凡的方案。”这个自由模板和我的其他五个约束模板配合反而比全程自由对话让我心智更清楚。最后再分享一个小技巧把你的模板仓库提交历史当成一本成长日记。每次你调整了什么规则、为什么调整都在commit message里写清楚。几个月后回头翻一翻你会看到自己从“AI对话使用者”变成“AI工作流程设计者”的整个轨迹这个过程本身比任何单个模板都有价值。
