我花了两个周末把 Claude Code 的模板体系彻底重写了一遍从一堆零零散散的提示词碎片整理成了现在这套可以跨项目复用的 claude-code-templates。说实话工具本身谁都学得会真正拉开效率差距的是你有没有把“已知的、重复的、可沉淀的东西”变成模板。今天这篇文章就把我这次的整理思路、具体模板内容、以及踩过的坑都聊透。这套东西不是给你看一遍就完的我会直接把模板文件的核心段落放出来标注清楚每个部分为什么这么写、改哪里能适配你自己的项目。适不适合你看三个问题就知道你是不是经常让 Claude Code 做同一类事情代码评审、写测试、补注释你是不是每次都要在对话里重新描述一遍上下文你是不是想让团队里的 AI 协作风格统一起来如果是这套 claude-code-templates 就是为你准备的。1. 为什么非做模板不可1.1 从“临时对话”到“长期资产”很多人用 Claude Code 的方式是打开终端输入一句话让 AI 干活干完就关。这种用法不是不对而是太浪费了。Claude Code 真正值钱的能力不是单次对话有多聪明而是它能不能在你重复做同一类工作时越做越顺。我举一个实际例子。以前我让 Claude Code 做代码评审每次都要花一两百字去描述规则你要关注什么问题、不要只夸代码写得好、要给出具体修改建议。这套描述我重复写了至少二十次。就算每次都写得差不多但细节总有出入输出质量就飘忽不定。后来我把它固化成一个code-review.template.md从此每次只要说一句“按模板 review 一下 staging 分支的改动”产出质量立刻稳定在同一个水平线。这就是模板存在的根本理由把不稳定的口头禅变成稳定的可复用资产。1.2 三个层级必须分清整理模板之前我对模板的存放层级完全没有概念什么文件都往全局目录塞。结果就是项目 A 的规则跑到项目 B 里去AI 判断混乱指令经常互相打架。现在我严格分了三层全局层放在~/.claude/templates/或$CLAUDE_CONFIG_DIR/templates/适合跟具体项目无关的通用任务比如通用代码评审、通用 Git 提交信息规范、通用 SQL 格式化标准。项目层放在项目根目录.claude/templates/下适合跟当前技术栈强绑定的模板比如“按项目现有框架风格写接口”“统一使用项目的错误码规范”。这一层通常通过项目内的 CLAUDE.md 引用。会话层/指令层不落盘临时写的短提示词或者通过/template运行时指令手动调用的某个模板。这种适合高度临时、复用价值低的碎片指令。层级一旦理清规则冲突概率大幅降低。全局层的东西不会污染项目层项目层的东西也不会泄露到别的仓库里。1.3 模板是如何被“拉起来”的Claude Code 加载模板的方式本质上是“上下文注入”。你在对话里调起模板或用 CLAUDE.md 让每个会话自动读到某些规则背后都是把模板文本塞进上下文窗口。理解这一点你就明白两个关键约束第一模板不是魔法它是纯文本拼接所以模板质量直接决定上下文质量。第二所有模板加起来不能太长因为上下文窗口是有限资源同一时刻加载的模板越多留给实际代码分析的余量就越少。我自己的量化经验是一次会话里全局模板 项目模板的总量控制在 6000 字以内。超过这个值Claude Code 会开始出现“记了规则忘了代码”的情况回答开始泛化、客套。我踩过这个坑后面章节会细说。2. 这套模板系统的设计思路2.1 按“任务类型”而不是“工具链”分类组织第一次整理时我犯了一个典型错误按“前端模板”“后端模板”“DevOps 模板”来组织文件夹。后来发现这么分类特别难用。技术栈是多变的真正稳定的是任务。你在 React 项目里需要做代码评审在 Go 项目里也需要做代码评审你在 JavaScript 里写单元测试在 Python 里照样写单元测试。所以我最终是按“任务”分类目录结构长这样templates/ ├── review/ │ ├── code-review.template.md │ ├── dependency-review.template.md │ └── security-spot-check.template.md ├── testing/ │ ├── unit-test.template.md │ ├── integration-test.template.md │ └── e2e-scenario.template.md ├── refactor/ │ ├── api-refactor.template.md │ ├── naming-cleanup.template.md │ └── dead-code-removal.template.md ├── project/ │ ├── scaffolding.template.md │ ├── dependency-audit.template.md │ └── readme-generation.template.md └── _hooks/ └── run-template.sh这样你在任何一个项目里遇到“要写测试了”第一反应是去testing/目录找对应模板而不是去想“我现在的项目是什么语言”。任务先于技术栈这个原则也是我推荐所有人组织 claude-code-templates 时的第一步。2.2 用“占位符”而不是写死项目名模板里最忌讳的是什么是把项目名、模块名、团队名写死。写死了换一个项目就得改模板改着改着就不想用了。我用占位符体系解决这个问题。模板里凡是需要上下文填充的位置统一写成{{PLACEHOLDER}}形式。比较实用的几个{{PROJECT_NAME}}当前项目名{{LANGUAGE_STACK}}主语言和技术栈{{FRAMEWORK}}核心框架{{TEST_FRAMEWORK}}测试框架{{CODE_STYLE}}约定风格如 “遵循项目内 .editorconfig eslint”{{SCOPE_LIMIT}}本次操作的范围边界实际效果是这样的我在 review 模板里写上“请针对{{SCOPE_LIMIT}}范围内的改动做评审”在使用时只需要把它替换成src/services/paymentAI 就会把注意力精准锁在那个目录而不是通读全仓库。占位符的命名必须一眼看懂。我见过有人用{a}{b}这种东西看起来省事但用模板的人根本不知道{a}该填什么这个模板就是失败的。2.3 指令要“具体到可执行”不要“抽象到没脾气”模板本质是一份给 AI 的说明书。如果你的模板里全是“请仔细分析代码”“注意潜在问题”这种万金油措辞那模板的意义就失去了——这些废话不写模板我也能说。好的模板指令应该具体到能产生可执行清单。举个例子我的 review 模板里不是只说“分析代码质量”而是明确要求对每个发现的问题给出严重级别标记P0/P1/P2必须指出文件路径 行号每个结论必须附上理由禁止无根据的“看起来可以优化”至少给出一个具体的修改建议不允许只报问题不给方案如果改动涉及对外 API必须单独列出兼容性影响AI 拿到这样的模板输出的东西才能直接拿去干活。模板的作用不是给 AI 增加背景知识而是给 AI 划定工作边界和输出格式——边界越清晰结果越可用。3. 核心模板逐字节拆解这一章是全文最硬核的部分。我会把我用得最频繁的几个模板完整放出来配合逐段解释。你可以直接复制去用也可以按自己的习惯改。3.1 代码评审模板先定边界再限产出这是我使用频率第一的模板没有之一。以前让 Claude Code 看代码它经常输出一堆“总体来看结构清晰、命名规范”这种废话俄而给一两条挑刺建议就结束了。这个模板专门治这种病。模板正文# Code Review Execution Template ## Context - 仓库: {{PROJECT_NAME}} - 技术栈: {{LANGUAGE_STACK}} - 评审范围: {{SCOPE_LIMIT}} - 基线分支: {{BASE_BRANCH}} ## Objectives 1. 只评审 {{SCOPE_LIMIT}} 内的变更禁止跳出范围讨论存量代码。 2. 输出格式必须为 Markdown 清单每项包含 - 文件路径和行号 - 严重级别: P0(会出事故/P1(明显缺陷)/P2(改进建议) - 问题描述和触发场景 - 具体的修改方案代码级 3. 至少给出3条有效问题不满足时说明“该范围内未发现更多有效问题”。 4. 存在 API 变更时必须额外列出兼容性风险。注意一个细节我在 Objectives 里强制要求“至少给出3条有效问题”。这一招是实测出来的如果不写这条AI 常常在找到一两个小问题后就停手输出显得很敷衍。用“质量不够数量凑”倒逼它深挖实测下来能多挖出不少真问题。另一个关键是“禁止跳出范围讨论存量代码”。AI 有一个坏习惯喜欢拿范围内的代码和范围外的旧代码做对比说着说着就开始点评别的文件。这条规则把它的注意力锁在 commit 之内评审效率大幅提升。3.2 性能问题定位模板先数据、再假设、后验证性能优化的场景最容易出现“AI 凭感觉猜瓶颈”。这个模板的目的就是让 AI 少猜、多看数据。尤其适合在性能压测发现问题后使用。模板核心段落## Constraints - 只允许基于已知指标或代码分析进行假设禁止空想可能的性能问题。 - 一切优化建议必须附带可度量的评估方式接口响应时间、GC 次数、CPU profile 数据等。 ## Procedure 1. 阅读范围 {{SCOPE_LIMIT}} 内的核心热点路径输出调用链图文本形式禁止 ASCII 之外的图。 2. 找出存在明显复杂度问题、重复计算、无效 IO 的具体代码位置。 3. 对每处问题给出修复前/修复后对比代码块。 4. 修复建议必须提供验证方式例如 - 压测命令 - 可观察指标 - 预期改善幅度 5. 如果某问题无法在本目录内修复标注为 cannot-fix-here并建议归属模块。说实话性能优化模板最难写因为性能问题高度依赖场景。后来我想通了模板不需要替 AI 找到瓶颈——模板只需要保证它不瞎猜。性能分析这件事最重要的是“可验证”。这条模板的存在价值就是把 AI 从“我觉得这里慢”校准到“这里存在一次 N1 查询每次请求多扫描约200行无用数据”。那个“无法在本目录内修复”的标注也很有用它让 AI 敢于承认自己做不了而不是硬给一个跨模块的虚假修复方案。3.3 单元测试生成模板边界优先、行为验证写单测这件事很多人的痛点是让 AI 生成的测试只会覆盖 happy path边界条件一概不测。我的测试模板专门解决这个。# Unit Test Generation Template ## Input/Output Contract - 被测对象: {{SCOPE_LIMIT}} - 测试框架: {{TEST_FRAMEWORK}} - 风格约束: {{CODE_STYLE}} ## Generation Rules 1. 首个用例必须是正常路径主流程确保基本行为正确。 2. 之后必须覆盖以下边界类型存在则保留不存在就说明理由 - 空输入/空集合 - 极大值/极小值边界溢出 - 非法格式或类型错误 - 超时/取消场景如适用 - 与外部依赖交互失败时的行为 3. 每个用例的命名必须体现被测行为test_method_condition_expect。 4. 禁止为了覆盖率凑无用断言断言必须验证业务结果而非语言自带行为。 5. 对无法确定的外部依赖用 mock 隔离并在注释中说明约定。这里最容易被忽视的是规则2。AI 生成测试太喜欢写“传一个合法参数断言结果正确”这种用例了敲入模板后它才会被迫思考空值、上限、异常路径。而规则4 则是反向约束不要为了行数而堆断言。AI 一旦被要求“高覆盖率”就爱写一堆断言变量不为null之类的废话这些断言没有任何业务价值。模板要把这种倾向压下去。3.4 新项目骨架整理模板先盘货、再动手每次新开一个项目Claude Code 都容易直接生成一堆它“觉得应该有”的文件。这个模板用于约束它先盘点信息再开始动手避免一个空项目被灌进满屏猜测代码。# Project Scaffolding Template ## Discovery Phase必须先执行禁止跳步 1. 先输出该项目的形态推断 - 预估目录结构 - 核心依赖清单 - 入口文件位置 2. 如果项目中已有 package manifestpackage.json / pyproject.toml / go.mod 必须基于现有 manifest 操作禁止自行添加未列出的依赖。 3. 不确定的内容必须输出 [DOUBT] 标记并询问禁止默默假设。 ## Generation Phase仅在确认后执行 1. 生成文件清单并逐文件说明用途。 2. 代码风格对齐 {{CODE_STYLE}}。 3. 输出时附上“生成文件树”文本。那条 “禁止跳步” 是精华。没有这一步AI 一上来就生成三十个文件项目根本没法用。加了 Discovery Phase 后它会先问你“用的是什么包管理器”“入口文件打算叫什么”这种关键问题。这套思路放在微服务拆分、模块重构时也一样适用,本质上就是“先对齐认知再让 AI 动手”。4. 用一个 Hook 脚本把模板“变成命令”模板放在目录里理论上你也可以直接手动复制内容粘贴到对话里。但那样效率太低违背了做模板的初衷。我在_hooks/里放了一个脚本把“读取模板 填入占位符 写入临时文件”这一套动作压缩成一个命令。#!/usr/bin/env bash # run-template.sh —— 将模板渲染为可直接粘贴/注入的指令内容 set -euo pipefail TEMPLATE_DIR${CLAUDE_TEMPLATE_DIR:-$HOME/.claude/templates} TEMPLATE_NAME${1:?用法: run-template.sh 模板名 [占位符替换] } TEMPLATE_FILE$TEMPLATE_DIR/$TEMPLATE_NAME.template.md if [[ ! -f $TEMPLATE_FILE ]]; then echo 找不到模板: $TEMPLATE_NAME 2 exit 1 fi # 先做基础替换例如把 {{PROJECT_NAME}} 替换为当前目录名 PROJECT_NAME$(basename $(pwd)) sed -e s/{{PROJECT_NAME}}/$PROJECT_NAME/g \ -e s/{{LANGUAGE_STACK}}/${LANG_STACK:-unknown}/g \ $TEMPLATE_FILE加了这段脚本之后我的日常操作变成这样LANG_STACKTypeScriptReact ./run-template.sh testing/unit-test输出出来的就是已经替换好项目名的完整指令直接粘进 Claude Code 对话即可。再进一步也可以把这个脚本挂到 Claude Code 原生的 commands / Scripts 能力上实现“斜杠命令”式的调用。Claude Code 本身支持自定义斜杠命令路径是.claude/commands/。把 wc 目录下的模板文件和 command 关联起来后你甚至可以直接在交互界面里输入/test就调起测试模板。这个组合技用熟了之后基本告别手打长提示词了。5. 常见问题与排查技巧实录5.1 模板加载了但表现不像模板这是最诡异的一种失败。明明把规则都写进模板了AI 回答起来还是天马行空。我排查了很多次之后发现根源往往在于“模板和其他规则打架”。具体来说项目 CLAUDE.md 里可能写着“所有输出要详细解释”而你的模板要求“只输出清单”。当两份指令在上下文中同时存在时AI 会试图调和这两个矛盾最终两头都做得不彻底。排查方法很简单临时把 CLAUDE.md 内容抽走只留模板看输出是否正常。如果正常就是规则冲突。不要试图让模板去打败 CLAUDE.md而是让模板在开头声明的优先级更高。比如在 review 模板第一行写上“本模板是一份独立评审要求除非用户另行说明否则优先级高于项目的一般性指导”。5.2 模板占位符替换后语义变形占位符替换不是简单的字符串替换要考虑语义。我举个踩过的坑我的命名清理模板里有个{{CODE_STYLE}}原本打算用来填“项目使用 snake_case”。有一次我直接替换成“项目使用 snake_case 但保持与现有 API 风格一致”这句话本身是矛盾的snake_case 和 API 驼峰风格结果 AI 在实施时出现了混乱命名。现在我的模板里对每个占位符都写明了“可接受值示例”例如- {{CODE_STYLE}}: 可选值为 google-java-style/prettier/eslintprettier/项目现有惯例_见CLAUDE.md这么一写调用模板的人就知道这里该怎么填不会随手塞一句含糊描述进去。5.3 上下文越来越长 输出越来越水把太多模板同时塞进上下文会让 Claude Code 的行为退化。我现在对模板加载实施“按需加载”原则同一次会话里最多激活两个模板。如果第三个模板也要用就先把前面的规则从上下文里“卸载”——简单说就是新开会话在会话描述里只带最新需要的模板。判断标准很简单如果你感觉 AI 的输出开始出现“好的根据您的需求我将……”这类空洞引语大概率就是上下文塞太满了。这时候删模板、开新会话输出新鲜感立刻回来。5.4 团队复制时模板风格被改得七零八落当模板开始在团队里流通风格失控是必然的。有人喜欢在里面加一堆 “请务必” 的强调有人喜欢精简到只剩五个词。到后面模板库会变成一锅粥。我的对策是全员统一 fork 一个 templates 仓库做任何修改都通过 PR 走评审。模板的改动和代码改动一样,需要理由和讨论。我自己给团队定了几条硬性约束供你参考模板段落实词必须保留“职责边界”类内容新增模板必须先回答“它替代了哪一次重复劳动”一个模板的字数上限建议通用模板 600 字专项模板 1500 字超过上限不是不让写而是要写清楚“这 1500 字里哪些是每次必须加载的哪些可以按需加载”。敢做减法的模板库才是能被团队长期使用的模板库。6. 模板的“开源心态”:持续演进的策略6.1 把自己当成第一个用户我在维护 claude-code-templates 时给自己定了一条规矩每个模板必须先被我自己连续用满两周才允许入库。两周之内发现任何不舒服的地方直接改。这不是繁琐而是能过滤掉大量“听起来不错但没人愿意用”的花架子。第一周我写了一批从来没派上用场的模板比如“会议纪要总结模板”和“周报生成模板”。后来发现这些东西对 AI 来说根本不值得单独做模板——一两句话就能说清楚做模板的成本反而高于收益。我现在删除模板库里的无用项比新增还勤快。6.2 模板是活文档如果你把模板当成“一次性提交就完事”的东西那它三个月后就会变成一堆谁都看不懂的化石。代码会腐化模板一样会腐化——技术栈变了、团队规范变了、AI 模型的能力边界变了模板都得跟着变。定期做模板审查的做法很实用每个迭代结束的周五花半小时看一下哪些模板在过去两周里完全没被调用。没被调用的模板要么说明功能不对要么说明入口不好找。我会选择删除或重构而不是留在仓库里占空间。6.3 注意可移植性与安全边界模板在团队或开源环境里传播的时候最要小心的是敏感信息问题。我见过一个团队把内部系统名、域名、甚至是数据库表名直接写进模板的示例代码里然后模板被 fork 出去。这种事故纯属人祸完全可以避免。我的项目里所有模板的示例代码和路径都改写为脱敏数据同时在 README 里明确写清楚模板仓库只允许放方法论不允许存放任何当前项目的真实凭据、内网地址和未公开的企业信息。这就是“模板开源心态”的安全底线。写在最后的几个实在建议根据我这两周重构 claude-code-templates 的实际体验给你五条可以直接上手的建议第一条从你做频次最高的三件事下手把它们各写一个模板不用多三个就够。一个负责日常评审一个负责测试一个负责重新整理项目结构先把最小闭环跑起来。第二条模板里一定要给自己留“表达怀疑”的空间。要让 AI 在发现规则不合适时敢于说“这里我按模板处理不了原因如下”而不是硬着头皮生成错误的结果。第三条模板的版本要跟你的 Claude Code 主版本同步更新不然有些旧指令在新模型下会失效或者语义漂移。第四条模板目录必须配一份 README写清楚每个模板是干嘛的、怎么用、适合什么场景。不要认为模板文件本身已经足够自解释等你三个月后回头看就明白了。第五条最后是个人喜好问题——我习惯把“禁止空谈、必须给到文件路径和具体操作”放在所有模板的前三条指令里这一招让我跟 AI 对话的效率直接翻倍。你上手之后也可以逐渐形成属于自己的“前三条指令”风格那时候这套 claude-code-templates 就真正变成你自己的东西了。 
长河君 · 2026/10/17 5:17:43 · 阅读 1.2k Claude Code模板体系重构：从临时对话到可复用资产
我花了两个周末把 Claude Code 的模板体系彻底重写了一遍从一堆零零散散的提示词碎片整理成了现在这套可以跨项目复用的 claude-code-templates。说实话工具本身谁都学得会真正拉开效率差距的是你有没有把“已知的、重复的、可沉淀的东西”变成模板。今天这篇文章就把我这次的整理思路、具体模板内容、以及踩过的坑都聊透。这套东西不是给你看一遍就完的我会直接把模板文件的核心段落放出来标注清楚每个部分为什么这么写、改哪里能适配你自己的项目。适不适合你看三个问题就知道你是不是经常让 Claude Code 做同一类事情代码评审、写测试、补注释你是不是每次都要在对话里重新描述一遍上下文你是不是想让团队里的 AI 协作风格统一起来如果是这套 claude-code-templates 就是为你准备的。1. 为什么非做模板不可1.1 从“临时对话”到“长期资产”很多人用 Claude Code 的方式是打开终端输入一句话让 AI 干活干完就关。这种用法不是不对而是太浪费了。Claude Code 真正值钱的能力不是单次对话有多聪明而是它能不能在你重复做同一类工作时越做越顺。我举一个实际例子。以前我让 Claude Code 做代码评审每次都要花一两百字去描述规则你要关注什么问题、不要只夸代码写得好、要给出具体修改建议。这套描述我重复写了至少二十次。就算每次都写得差不多但细节总有出入输出质量就飘忽不定。后来我把它固化成一个code-review.template.md从此每次只要说一句“按模板 review 一下 staging 分支的改动”产出质量立刻稳定在同一个水平线。这就是模板存在的根本理由把不稳定的口头禅变成稳定的可复用资产。1.2 三个层级必须分清整理模板之前我对模板的存放层级完全没有概念什么文件都往全局目录塞。结果就是项目 A 的规则跑到项目 B 里去AI 判断混乱指令经常互相打架。现在我严格分了三层全局层放在~/.claude/templates/或$CLAUDE_CONFIG_DIR/templates/适合跟具体项目无关的通用任务比如通用代码评审、通用 Git 提交信息规范、通用 SQL 格式化标准。项目层放在项目根目录.claude/templates/下适合跟当前技术栈强绑定的模板比如“按项目现有框架风格写接口”“统一使用项目的错误码规范”。这一层通常通过项目内的 CLAUDE.md 引用。会话层/指令层不落盘临时写的短提示词或者通过/template运行时指令手动调用的某个模板。这种适合高度临时、复用价值低的碎片指令。层级一旦理清规则冲突概率大幅降低。全局层的东西不会污染项目层项目层的东西也不会泄露到别的仓库里。1.3 模板是如何被“拉起来”的Claude Code 加载模板的方式本质上是“上下文注入”。你在对话里调起模板或用 CLAUDE.md 让每个会话自动读到某些规则背后都是把模板文本塞进上下文窗口。理解这一点你就明白两个关键约束第一模板不是魔法它是纯文本拼接所以模板质量直接决定上下文质量。第二所有模板加起来不能太长因为上下文窗口是有限资源同一时刻加载的模板越多留给实际代码分析的余量就越少。我自己的量化经验是一次会话里全局模板 项目模板的总量控制在 6000 字以内。超过这个值Claude Code 会开始出现“记了规则忘了代码”的情况回答开始泛化、客套。我踩过这个坑后面章节会细说。2. 这套模板系统的设计思路2.1 按“任务类型”而不是“工具链”分类组织第一次整理时我犯了一个典型错误按“前端模板”“后端模板”“DevOps 模板”来组织文件夹。后来发现这么分类特别难用。技术栈是多变的真正稳定的是任务。你在 React 项目里需要做代码评审在 Go 项目里也需要做代码评审你在 JavaScript 里写单元测试在 Python 里照样写单元测试。所以我最终是按“任务”分类目录结构长这样templates/ ├── review/ │ ├── code-review.template.md │ ├── dependency-review.template.md │ └── security-spot-check.template.md ├── testing/ │ ├── unit-test.template.md │ ├── integration-test.template.md │ └── e2e-scenario.template.md ├── refactor/ │ ├── api-refactor.template.md │ ├── naming-cleanup.template.md │ └── dead-code-removal.template.md ├── project/ │ ├── scaffolding.template.md │ ├── dependency-audit.template.md │ └── readme-generation.template.md └── _hooks/ └── run-template.sh这样你在任何一个项目里遇到“要写测试了”第一反应是去testing/目录找对应模板而不是去想“我现在的项目是什么语言”。任务先于技术栈这个原则也是我推荐所有人组织 claude-code-templates 时的第一步。2.2 用“占位符”而不是写死项目名模板里最忌讳的是什么是把项目名、模块名、团队名写死。写死了换一个项目就得改模板改着改着就不想用了。我用占位符体系解决这个问题。模板里凡是需要上下文填充的位置统一写成{{PLACEHOLDER}}形式。比较实用的几个{{PROJECT_NAME}}当前项目名{{LANGUAGE_STACK}}主语言和技术栈{{FRAMEWORK}}核心框架{{TEST_FRAMEWORK}}测试框架{{CODE_STYLE}}约定风格如 “遵循项目内 .editorconfig eslint”{{SCOPE_LIMIT}}本次操作的范围边界实际效果是这样的我在 review 模板里写上“请针对{{SCOPE_LIMIT}}范围内的改动做评审”在使用时只需要把它替换成src/services/paymentAI 就会把注意力精准锁在那个目录而不是通读全仓库。占位符的命名必须一眼看懂。我见过有人用{a}{b}这种东西看起来省事但用模板的人根本不知道{a}该填什么这个模板就是失败的。2.3 指令要“具体到可执行”不要“抽象到没脾气”模板本质是一份给 AI 的说明书。如果你的模板里全是“请仔细分析代码”“注意潜在问题”这种万金油措辞那模板的意义就失去了——这些废话不写模板我也能说。好的模板指令应该具体到能产生可执行清单。举个例子我的 review 模板里不是只说“分析代码质量”而是明确要求对每个发现的问题给出严重级别标记P0/P1/P2必须指出文件路径 行号每个结论必须附上理由禁止无根据的“看起来可以优化”至少给出一个具体的修改建议不允许只报问题不给方案如果改动涉及对外 API必须单独列出兼容性影响AI 拿到这样的模板输出的东西才能直接拿去干活。模板的作用不是给 AI 增加背景知识而是给 AI 划定工作边界和输出格式——边界越清晰结果越可用。3. 核心模板逐字节拆解这一章是全文最硬核的部分。我会把我用得最频繁的几个模板完整放出来配合逐段解释。你可以直接复制去用也可以按自己的习惯改。3.1 代码评审模板先定边界再限产出这是我使用频率第一的模板没有之一。以前让 Claude Code 看代码它经常输出一堆“总体来看结构清晰、命名规范”这种废话俄而给一两条挑刺建议就结束了。这个模板专门治这种病。模板正文# Code Review Execution Template ## Context - 仓库: {{PROJECT_NAME}} - 技术栈: {{LANGUAGE_STACK}} - 评审范围: {{SCOPE_LIMIT}} - 基线分支: {{BASE_BRANCH}} ## Objectives 1. 只评审 {{SCOPE_LIMIT}} 内的变更禁止跳出范围讨论存量代码。 2. 输出格式必须为 Markdown 清单每项包含 - 文件路径和行号 - 严重级别: P0(会出事故/P1(明显缺陷)/P2(改进建议) - 问题描述和触发场景 - 具体的修改方案代码级 3. 至少给出3条有效问题不满足时说明“该范围内未发现更多有效问题”。 4. 存在 API 变更时必须额外列出兼容性风险。注意一个细节我在 Objectives 里强制要求“至少给出3条有效问题”。这一招是实测出来的如果不写这条AI 常常在找到一两个小问题后就停手输出显得很敷衍。用“质量不够数量凑”倒逼它深挖实测下来能多挖出不少真问题。另一个关键是“禁止跳出范围讨论存量代码”。AI 有一个坏习惯喜欢拿范围内的代码和范围外的旧代码做对比说着说着就开始点评别的文件。这条规则把它的注意力锁在 commit 之内评审效率大幅提升。3.2 性能问题定位模板先数据、再假设、后验证性能优化的场景最容易出现“AI 凭感觉猜瓶颈”。这个模板的目的就是让 AI 少猜、多看数据。尤其适合在性能压测发现问题后使用。模板核心段落## Constraints - 只允许基于已知指标或代码分析进行假设禁止空想可能的性能问题。 - 一切优化建议必须附带可度量的评估方式接口响应时间、GC 次数、CPU profile 数据等。 ## Procedure 1. 阅读范围 {{SCOPE_LIMIT}} 内的核心热点路径输出调用链图文本形式禁止 ASCII 之外的图。 2. 找出存在明显复杂度问题、重复计算、无效 IO 的具体代码位置。 3. 对每处问题给出修复前/修复后对比代码块。 4. 修复建议必须提供验证方式例如 - 压测命令 - 可观察指标 - 预期改善幅度 5. 如果某问题无法在本目录内修复标注为 cannot-fix-here并建议归属模块。说实话性能优化模板最难写因为性能问题高度依赖场景。后来我想通了模板不需要替 AI 找到瓶颈——模板只需要保证它不瞎猜。性能分析这件事最重要的是“可验证”。这条模板的存在价值就是把 AI 从“我觉得这里慢”校准到“这里存在一次 N1 查询每次请求多扫描约200行无用数据”。那个“无法在本目录内修复”的标注也很有用它让 AI 敢于承认自己做不了而不是硬给一个跨模块的虚假修复方案。3.3 单元测试生成模板边界优先、行为验证写单测这件事很多人的痛点是让 AI 生成的测试只会覆盖 happy path边界条件一概不测。我的测试模板专门解决这个。# Unit Test Generation Template ## Input/Output Contract - 被测对象: {{SCOPE_LIMIT}} - 测试框架: {{TEST_FRAMEWORK}} - 风格约束: {{CODE_STYLE}} ## Generation Rules 1. 首个用例必须是正常路径主流程确保基本行为正确。 2. 之后必须覆盖以下边界类型存在则保留不存在就说明理由 - 空输入/空集合 - 极大值/极小值边界溢出 - 非法格式或类型错误 - 超时/取消场景如适用 - 与外部依赖交互失败时的行为 3. 每个用例的命名必须体现被测行为test_method_condition_expect。 4. 禁止为了覆盖率凑无用断言断言必须验证业务结果而非语言自带行为。 5. 对无法确定的外部依赖用 mock 隔离并在注释中说明约定。这里最容易被忽视的是规则2。AI 生成测试太喜欢写“传一个合法参数断言结果正确”这种用例了敲入模板后它才会被迫思考空值、上限、异常路径。而规则4 则是反向约束不要为了行数而堆断言。AI 一旦被要求“高覆盖率”就爱写一堆断言变量不为null之类的废话这些断言没有任何业务价值。模板要把这种倾向压下去。3.4 新项目骨架整理模板先盘货、再动手每次新开一个项目Claude Code 都容易直接生成一堆它“觉得应该有”的文件。这个模板用于约束它先盘点信息再开始动手避免一个空项目被灌进满屏猜测代码。# Project Scaffolding Template ## Discovery Phase必须先执行禁止跳步 1. 先输出该项目的形态推断 - 预估目录结构 - 核心依赖清单 - 入口文件位置 2. 如果项目中已有 package manifestpackage.json / pyproject.toml / go.mod 必须基于现有 manifest 操作禁止自行添加未列出的依赖。 3. 不确定的内容必须输出 [DOUBT] 标记并询问禁止默默假设。 ## Generation Phase仅在确认后执行 1. 生成文件清单并逐文件说明用途。 2. 代码风格对齐 {{CODE_STYLE}}。 3. 输出时附上“生成文件树”文本。那条 “禁止跳步” 是精华。没有这一步AI 一上来就生成三十个文件项目根本没法用。加了 Discovery Phase 后它会先问你“用的是什么包管理器”“入口文件打算叫什么”这种关键问题。这套思路放在微服务拆分、模块重构时也一样适用,本质上就是“先对齐认知再让 AI 动手”。4. 用一个 Hook 脚本把模板“变成命令”模板放在目录里理论上你也可以直接手动复制内容粘贴到对话里。但那样效率太低违背了做模板的初衷。我在_hooks/里放了一个脚本把“读取模板 填入占位符 写入临时文件”这一套动作压缩成一个命令。#!/usr/bin/env bash # run-template.sh —— 将模板渲染为可直接粘贴/注入的指令内容 set -euo pipefail TEMPLATE_DIR${CLAUDE_TEMPLATE_DIR:-$HOME/.claude/templates} TEMPLATE_NAME${1:?用法: run-template.sh 模板名 [占位符替换] } TEMPLATE_FILE$TEMPLATE_DIR/$TEMPLATE_NAME.template.md if [[ ! -f $TEMPLATE_FILE ]]; then echo 找不到模板: $TEMPLATE_NAME 2 exit 1 fi # 先做基础替换例如把 {{PROJECT_NAME}} 替换为当前目录名 PROJECT_NAME$(basename $(pwd)) sed -e s/{{PROJECT_NAME}}/$PROJECT_NAME/g \ -e s/{{LANGUAGE_STACK}}/${LANG_STACK:-unknown}/g \ $TEMPLATE_FILE加了这段脚本之后我的日常操作变成这样LANG_STACKTypeScriptReact ./run-template.sh testing/unit-test输出出来的就是已经替换好项目名的完整指令直接粘进 Claude Code 对话即可。再进一步也可以把这个脚本挂到 Claude Code 原生的 commands / Scripts 能力上实现“斜杠命令”式的调用。Claude Code 本身支持自定义斜杠命令路径是.claude/commands/。把 wc 目录下的模板文件和 command 关联起来后你甚至可以直接在交互界面里输入/test就调起测试模板。这个组合技用熟了之后基本告别手打长提示词了。5. 常见问题与排查技巧实录5.1 模板加载了但表现不像模板这是最诡异的一种失败。明明把规则都写进模板了AI 回答起来还是天马行空。我排查了很多次之后发现根源往往在于“模板和其他规则打架”。具体来说项目 CLAUDE.md 里可能写着“所有输出要详细解释”而你的模板要求“只输出清单”。当两份指令在上下文中同时存在时AI 会试图调和这两个矛盾最终两头都做得不彻底。排查方法很简单临时把 CLAUDE.md 内容抽走只留模板看输出是否正常。如果正常就是规则冲突。不要试图让模板去打败 CLAUDE.md而是让模板在开头声明的优先级更高。比如在 review 模板第一行写上“本模板是一份独立评审要求除非用户另行说明否则优先级高于项目的一般性指导”。5.2 模板占位符替换后语义变形占位符替换不是简单的字符串替换要考虑语义。我举个踩过的坑我的命名清理模板里有个{{CODE_STYLE}}原本打算用来填“项目使用 snake_case”。有一次我直接替换成“项目使用 snake_case 但保持与现有 API 风格一致”这句话本身是矛盾的snake_case 和 API 驼峰风格结果 AI 在实施时出现了混乱命名。现在我的模板里对每个占位符都写明了“可接受值示例”例如- {{CODE_STYLE}}: 可选值为 google-java-style/prettier/eslintprettier/项目现有惯例_见CLAUDE.md这么一写调用模板的人就知道这里该怎么填不会随手塞一句含糊描述进去。5.3 上下文越来越长 输出越来越水把太多模板同时塞进上下文会让 Claude Code 的行为退化。我现在对模板加载实施“按需加载”原则同一次会话里最多激活两个模板。如果第三个模板也要用就先把前面的规则从上下文里“卸载”——简单说就是新开会话在会话描述里只带最新需要的模板。判断标准很简单如果你感觉 AI 的输出开始出现“好的根据您的需求我将……”这类空洞引语大概率就是上下文塞太满了。这时候删模板、开新会话输出新鲜感立刻回来。5.4 团队复制时模板风格被改得七零八落当模板开始在团队里流通风格失控是必然的。有人喜欢在里面加一堆 “请务必” 的强调有人喜欢精简到只剩五个词。到后面模板库会变成一锅粥。我的对策是全员统一 fork 一个 templates 仓库做任何修改都通过 PR 走评审。模板的改动和代码改动一样,需要理由和讨论。我自己给团队定了几条硬性约束供你参考模板段落实词必须保留“职责边界”类内容新增模板必须先回答“它替代了哪一次重复劳动”一个模板的字数上限建议通用模板 600 字专项模板 1500 字超过上限不是不让写而是要写清楚“这 1500 字里哪些是每次必须加载的哪些可以按需加载”。敢做减法的模板库才是能被团队长期使用的模板库。6. 模板的“开源心态”:持续演进的策略6.1 把自己当成第一个用户我在维护 claude-code-templates 时给自己定了一条规矩每个模板必须先被我自己连续用满两周才允许入库。两周之内发现任何不舒服的地方直接改。这不是繁琐而是能过滤掉大量“听起来不错但没人愿意用”的花架子。第一周我写了一批从来没派上用场的模板比如“会议纪要总结模板”和“周报生成模板”。后来发现这些东西对 AI 来说根本不值得单独做模板——一两句话就能说清楚做模板的成本反而高于收益。我现在删除模板库里的无用项比新增还勤快。6.2 模板是活文档如果你把模板当成“一次性提交就完事”的东西那它三个月后就会变成一堆谁都看不懂的化石。代码会腐化模板一样会腐化——技术栈变了、团队规范变了、AI 模型的能力边界变了模板都得跟着变。定期做模板审查的做法很实用每个迭代结束的周五花半小时看一下哪些模板在过去两周里完全没被调用。没被调用的模板要么说明功能不对要么说明入口不好找。我会选择删除或重构而不是留在仓库里占空间。6.3 注意可移植性与安全边界模板在团队或开源环境里传播的时候最要小心的是敏感信息问题。我见过一个团队把内部系统名、域名、甚至是数据库表名直接写进模板的示例代码里然后模板被 fork 出去。这种事故纯属人祸完全可以避免。我的项目里所有模板的示例代码和路径都改写为脱敏数据同时在 README 里明确写清楚模板仓库只允许放方法论不允许存放任何当前项目的真实凭据、内网地址和未公开的企业信息。这就是“模板开源心态”的安全底线。写在最后的几个实在建议根据我这两周重构 claude-code-templates 的实际体验给你五条可以直接上手的建议第一条从你做频次最高的三件事下手把它们各写一个模板不用多三个就够。一个负责日常评审一个负责测试一个负责重新整理项目结构先把最小闭环跑起来。第二条模板里一定要给自己留“表达怀疑”的空间。要让 AI 在发现规则不合适时敢于说“这里我按模板处理不了原因如下”而不是硬着头皮生成错误的结果。第三条模板的版本要跟你的 Claude Code 主版本同步更新不然有些旧指令在新模型下会失效或者语义漂移。第四条模板目录必须配一份 README写清楚每个模板是干嘛的、怎么用、适合什么场景。不要认为模板文件本身已经足够自解释等你三个月后回头看就明白了。第五条最后是个人喜好问题——我习惯把“禁止空谈、必须给到文件路径和具体操作”放在所有模板的前三条指令里这一招让我跟 AI 对话的效率直接翻倍。你上手之后也可以逐渐形成属于自己的“前三条指令”风格那时候这套 claude-code-templates 就真正变成你自己的东西了。