如果你用 Claude Code 写过超过一个项目一定会有这种体会同一个提示词在不同目录下表现天差地别。不是模型不稳定而是你每次都在重新教育它。几个月前我把高频使用的提示词整理成了一套可复用的模板库文件名就叫claude-code-templates用 Git 管理从一个人用到后来拉进团队共用省掉的不只是反复打字的时间更重要的是让 AI 的输出质量和边界控制变得可预期。这套模板库本质上是一批预先写好的指令文件告诉 Claude Code 它是谁、要做什么、有什么限制、按什么格式输出。它解决的不是“写不出好提示词”的问题而是“同一个好提示词无法被重复使用”的问题。如果你被 AI 编程助手的自由发挥坑过或者想统一团队的代码审查、重构、测试口径又或者单纯想把自己的工作流固化下来这套思路都值得参考。下面我把设计思路、模板构成、落地实操和常见坑完整拆开讲一遍。这不是理论推演是我在真实项目里反复改出来的经验。1. 为什么我非要把 Claude Code 提示词沉淀成模板1.1 Claude Code 会话的“失忆”特性Claude Code 这类终端编程助手和网页版聊天最大的区别是它工作在一个会持续变动的项目上下文里。它会读目录结构、看文件内容、执行命令但这些能力同时也带来一个副作用每一轮对话其实都在重新建立上下文窗口。你可能会觉得自己已经在提示词里写得足够清楚了“你是一个资深 Python 开发帮我审查代码注意性能问题。”但换一个目录、换一个项目甚至过了半天再来它就把这些背景信息忘得干干净净。你自己也懒得每次敲一长串于是只能接受一个“泛泛而谈”的输出。这不是模型智商的问题而是没有给工作流加上“记忆锚点”。模板库解决的就是这件事把角色设定、行为约束、输出格式固定成文件让它每次被调用时都能精确加载。想通这一点后我立刻从“写提示词”转到了“写模板”。1.2 模板按什么维度分类才不踩坑早先我尝试把所有提示词塞进一个超大的CLAUDE.md后来发现这是个馊主意。文件越长模型注意力越分散可能你真正想强调的审查规则反而被边缘化。正确做法是按“任务类型”拆分而不是按“项目”整体写。我现在的模板库分四类你可以直接参考这种分法类型对应场景触发方式角色模板定义 AI 身份如后端开发、代码审查员、测试工程师放入.claude/commands/或手动引入任务模板具体操作如重构某个文件、补全测试、写提交信息命令式调用工作流模板多步骤串联如“改代码→跑测试→生成变更说明”组合多个命令或脚本规则模板项目通用约束如禁止改动生成文件、依赖锁定方式放入CLAUDE.md全局生效这个分类背后有一个重要原则角色和任务分离通用规则和临时指令分离。角色模板负责“我是谁”任务模板负责“做什么”规则模板负责“绝不能碰什么”。三者各司其职才能在复用时不被互相干扰。1.3 为什么选择文件化管理而不是记忆聊天有人会说直接在对话里跟 Claude Code.talk 一次它当场记住了不就行了确实可以但问题有两个。第一会话上下文有限聊了一会儿新指令就会把旧指令挤出窗口第二终端里塞一大段自然语言描述回头想复用还得翻历史记录既不可维护也不可审查。把模板落成文件等于给每个高频操作建了“标准操作卡”。团队新人来了不需要你手把手教他“我们公司审查代码要关注什么”他只要运行/code-review就能得到一套统一的审查框架。文件化管理还能放进 Git 做 diff让团队对提示词的改动都有据可查。2. 模板核心构成好的提示词模板长什么样2.1 角色、任务、约束、输出四件套我在反复迭代中总结出一条经验任何任务型模板只要包含四部分就会比随手写的一句提示词稳定得多。它们分别是角色role、任务task、约束constraints、输出格式output format。角色部分是让 Claude Code 切换到特定专家视角比如“你是一名有 10 年经验的后端架构师”。任务部分要写清楚边界比如“只审查这个 PR 涉及的 3 个文件”。约束部分最关键要明确禁止动作比如“不修改代码只输出建议”“不要触碰生成文件目录”。输出格式部分则统一了结果的形态让它每次都能生成可解析的列表或表格。这四部分的顺序也有讲究。角色放在最前面相当于给模型立一个“人设”后面的指令会天然靠向这个身份。任务和约束紧跟其后最后才指定输出格式。如果一开始就给格式模板模型会过于关注排版而忽略真正的分析任务。2.2 变量替换与上下文注入的两种方式模板如果只是死板的一篇文章复用价值会大打折扣。真正好用的模板必须有“插槽”。我常用的做法是两种命令参数注入和文件路径通配。在.claude/commands/下定义的命令文件可以通过参数提示引导用户输入文件路径或关键词。比如写一个review.md用户执行/review src/utils/parser.js src/api/client.js模板内部就能拿到这些路径作为待审查对象。另一种方式是让模板里写清楚“自动查找当前分支变化的文件”Claude Code 本身具备 Git 能力可以自己执行命令去定位变更范围。这里有个容易犯的错上下文注入不是越多越好。把整个项目的文件列表塞进模板会让模型陷入信息过载反而抓不住重点。我一般只注入两类信息一类是目标对象的路径另一类是本次任务的核心约束关键词。其余信息让模型按需去读文件。2.3 不同任务类型的模板写法差异同样是四件套写代码审查模板和写重构模板的侧重点完全不一样。审查类模板要把“禁掉什么”说死比如“不要自行修复只输出问题”因为审查场景最怕 AI 顺手改代码。重构类模板则恰恰相反要允许“修改代码”但必须要求“保持原有测试通过”。测试生成模板又是另一套逻辑它需要非常具体的输入输出示例因为模型的想象力太丰富了不给例子它就会编造不存在的接口。我写过的最小可用测试模板至少包含一个“被测函数真实调用方式”的示例以及“断言库选型”的硬性要求。这些差异本质上是任务风险模型不同审查怕越界重构怕破坏测试怕失真。模板的自定义要围绕“这个任务最怕什么”来写约束而不是通用地写一堆“请严谨”“请高质量”这种没人知道怎么执行的话。3. 实操从零搭建自己的 claude-code-templates3.1 目录结构与命名规范我的模板库目录结构长这样你可以直接抄claude-code-templates/ ├── CLAUDE.md # 全局规则描述模板库本身 ├── commands/ │ ├── review.md # /review 代码审查 │ ├── refactor.md # /refactor 重构指定文件 │ ├── test.md # /test 生成单元测试 │ ├── commit.md # /commit 生成规范提交信息 │ └── workflow-diff.md # /workflow-diff 双文件对比分析 └── scripts/ ├── parse_args.js # 解析复杂参数的小脚本 └── check_diff.sh # 获取当前 Git 变更文件命名规范我坚持三条全小写字母用连字符分隔单词动词开头。原因很实际Claude Code 的斜杠命令是大小写敏感的全小写能避免刚输入时切换大小写的中断感。动词开头则让命令在脑海里形成“动作”暗示比如我想要审查就会下意识敲/review。3.2 三个可直接复用的核心模板先看代码审查模板这是我最常用也最稳定的一份--- description: 审查当前分支变更的代码文件 argument-hint: 可选传入具体文件路径不传则自动查找 Git 变更文件 --- 你是一名资深代码审查工程师擅长发现潜在的缺陷、性能瓶颈和可维护性问题。 # 任务 审查指定的文件从正确性、性能、安全、可维护性四个维度分析。 # 约束 - 只审查用户传入的文件如果没传文件就通过 git diff --name-only HEAD 自动发现变更文件 - 不要修改任何代码只输出审查意见 - 不要审查生成目录、依赖文件、二进制文件 - 每个问题必须标记严重级别blocker / major / minor - 用中文输出但代码标识符保持英文原样 # 输出格式 ## 审查摘要 说明本次审查范围和整体结论。 ## 问题列表 | 严重级别 | 文件 | 行号 | 问题描述 | 修改建议 | ## 重点提醒 最多列 3 个最值得优先处理的问题。这份模板最核心的一条约束是“不要修改任何代码”。很多审查任务翻车就是因为 Claude Code 一看到问题就顺手 patch 了。把这句话钉在模板里输出边界立刻清晰很多。再看测试生成模板--- description: 为指定模块生成单元测试 argument-hint: 模块文件路径如 src/utils/date.ts --- 你是一名测试工程师精通 pytest、Jest、Vitest。 # 任务 为 {FILENAME} 中导出的每个函数/类编写单元测试。 # 约束 - 先读取被测文件列出所有导出对象 - 只写当前测试框架下可运行的用例不要引入额外依赖 - 每个测试用例必须包含 Arrange、Act、Assert 三段结构 - mock 只允许 mock 外部副作用不允许 mock 被测函数内部逻辑 - 如果被测函数有边界条件必须补充边界用例 - 输出为完整测试文件不要省略或写“略” # 输出格式 文件名{FILENAME}.test.ts 测试文件正文这个模板里“必须补充边界用例”那句非常关键不然 AI 会挑好写的路径测试空数组、空字符串、非法入参全给漏掉。重构模板我一般这样写--- description: 在不改变对外行为的前提下重构指定文件 argument-hint: 需要重构的文件路径 --- 你是一名专注于代码质量的软件工程师。 # 任务 重构 {FILENAME}提升可读性和可维护性。 # 约束 - 必须保持对外接口和函数签名完全不变 - 重构后运行项目现有测试确保全部通过 - 不改变任何业务逻辑只做结构优化 - 修改后输出一份简短的变更说明列出每个重构动作的原因 - 如果发现原有代码有潜在 bug在“附加发现”部分单独标注不要混入重构动作 # 输出格式 ## 重构动作 按文件修改点逐个列出。 ## 新增改动原因 解释每个动作解决了什么问题。 ## 附加发现 这里列重构中发现但未处理的潜在问题。这种写法的价值在于强制把“结构性改动”和“疑似 bug”分开避免模型把 bug 修复悄悄混进重构里让 diff 审查变得极其痛苦。3.3 如何让 Claude Code 自动加载模板模板文件不是放对了位置就会自动生效还需要理解加载机制。Claude Code 启动时会读取项目根目录的CLAUDE.md作为长期规则这部分对所有会话生效适合放项目通用约束。而commands/目录下的文件则作为斜杠命令被动态注册执行/就能看到命令列表。具体操作上我会把模板库里真正的“规则条款”抽到CLAUDE.md比如“禁止修改 public 目录下编译产物”“所有生成代码必须附带测试”。而任务型模板放进commands/。这样做的好处是规则始终在场任务按需调用不会出现一边强调不要动产物目录一边又在某个命令模板里让它“清理编译垃圾”的矛盾。如果你希望模板库跟着项目走就把整个模板目录放进目标仓库如果希望全局生效可以把它放到 Claude Code 的用户目录下让它成为跨项目的个人命令库。两种方式我都试过强烈建议先用项目级目录等沉淀稳定了再升级成全局配置。3.4 参数传递与命令调用的现场记录以代码审查为例实际操作中的调用方式两种都有。手动指定文件/review src/utils/date.ts src/api/client.ts自动发现变更文件/review自动发现依赖的是模板里“通过git diff --name-only HEAD自动发现”那句话。Claude Code 会执行这个 Git 命令解析变更清单像我在现场盯着它做了一遍又一遍最终效果是它能准确避开package-lock.json这类文件。参数解析有个需要留意的点如果你传路径时没加引号路径里有空格就会出问题。建议在模板描述里明确写一句“路径请用英文双引号包裹”。这不是模板代码的问题而是终端和命令解析共同决定的规则踩过一次后就刻在说明里了。3.5 模板驱动的完整操作流程这里按一次“提交前代码检查”的完整操作说说你能直观看出模板如何组合使用。第一步运行/review让 Claude Code 自动梳理当前分支变更输出问题清单。第二步把审查结果里的 major 问题挑出来运行/refactor src/module.ts让模型做定向重构。第三步运行/test src/module.ts补上缺失的测试。第四步运行/commit生成符合规范的现代提交信息。这四步每步都调用独立模板但因为上下文窗口还保留着前面的分析结果步骤之间不会丢失联系。整体看模板库不是让你一次性把所有事干完而是把“分析—重构—测试—提交”拆成有边界感的操作环节。边界感强了AI 出错的概率就低了出了问题也好定位。4. 模板库落地中的常见问题与排查技巧4.1 模板加载了但没生效最常见的现象是人明明在项目目录里敲了/review结果 Clude Code 回答“未找到该命令”。这时先别怀疑文件内容先看后缀名。命令文件必须使用.md后缀且文件名必须没有多余标点。我之前吃过亏的是把文件名叫review.template.mdClaude Code 认不出它。第二个原因是目录层级不对。只有.claude/commands/目录下的文件才会被注册为斜杠命令我最初放在.github/commands/里自然不生效。如果确实放在正确目录还是不识别检查文件首部是否有畸形的 YAML frontmatter。frontmatter 必须位于文件最开头且被两条---包裹中间不能有空行出现格式问题时模型会直接不认这个文件。4.2 指令冲突与上下文覆盖模板库变大后指令冲突是我的噩梦。典型情况是CLAUDE.md里写了“不要修改测试文件”但某个命令模板里又要求“如果测试缺失帮生成测试文件”。两条规则在同一轮对话里相遇模型往往更倾向遵循更具体的、离它最近的那条指令结果就把全局规则踩了。排查这类冲突的办法是用一个叫规则体检的脚本脚本式命令把每个模板中的约束条款提取出来人工看一遍是否有互相矛盾的关键词。我在模板库里加了一份conflict_check.md专门把“禁止”“不能”“必须”“不要”这些词列出来做统一审查。我的经验是任何全局规则在CLAUDE.md中只保留“不可谈条件”的底线比如“严禁删除锁定文件”所有可被任务覆盖的规则尽量下沉到具体命令模板。这样上下级规则之间就不会频繁打架。4.3 长输出被截断怎么办模板设置的输出格式太复杂时Claude Code 经常在生成一半时达到输出上限尤其是代码审查表格式输出几十个问题列下来很容易断。这里有两个解决方向。第一压缩输出格式。把“每个问题一行包含文件:行号:严重级别:建议”这种压缩格式作为默认选项把完整表格作为--verbose模式的选项。第二主动拆任务。在模板里写一句“如果问题数量超过 12 个先只输出 blocker 和 major 级别minor 级在最后追加”。防截断不能靠“让它快点写”要靠给模型一个可控的出口。我在审查模板里加了“先输出 summary再逐块输出列表”的顺序要求这样即使真的被中断前面的摘要也已经出来了损失可控。4.4 团队模板同步的版本管理模板库从单人到团队后最大的变化是“再也不能随手改文件”。因为每个开发者的使用习惯不同有人希望审查严格点有人希望更宽松直接就改模板会造成很大的混乱。我建议的协作方式是模板库独立成一个 Git 仓库所有模板的改动走 Pull Request保留两层审查一层是技术正确性一层是措辞清晰度。每次改动需要同时在命令描述和CLAUDE.md里同步更新避免命令改了说明文本还停留在旧版本。更新到项目里的方式用 Git submodule 或者构建脚本复制都可以。我倾向于用复制脚本把模板库同步到各个项目保留一个version.txt文件谁在哪个模板版本上遇到的问题就能快速定位。这样比所有人直接用同一个远端仓库更可控也不至于有人改了立刻影响到生产环境。5. 从模板到工作流再往前迈一步5.1 用变量和外部命令让模板“活”起来静态模板解决了“每次重复输入长篇大论”的问题但还没解决“让模型拿到实时数据”的问题。在一些复杂场景里我会让模板调用外部脚本来获取动态信息。比如在工作流模板里写# 任务 先运行 ./scripts/check_diff.sh 获取当前变更文件清单再基于清单执行审查。这样模板就不再是一篇静态提示词而是一个“能自己收集环境的智能工作流”。要注意的是让模板执行脚本时必须限定脚本路径不能让它手一滑去跑rm。我在所有涉及外部命令的模板里都会加一句“只允许执行项目根目录下scripts/文件夹中的脚本”并且每次执行前确认命令内容。5.2 模板效果度量与迭代模板不是写完就能一劳永逸的。我的迭代方法是给每个模板加了一个“失败信号列表”每当模型输出明显偏离预期就把当时的对话标记为一次失败案例按月统计哪些模板最常触发偏离。比如审查模板一开始没有“不要修改代码”的约束我统计到一个星期内它擅自改动代码三次。后来把这条约束写进模板偏离率立刻降下来。所以我的建议是不要凭感觉改模板先记录失败场景再用失败场景反推需要新增或调整的约束条款。迭代原则是“一次只改一个变量”。改完跑三个历史案例看输出是否更符合预期再决定保留还是回滚。模板库本质上是提示词工程而提示词工程最忌讳的就是一次堆一屏改动最后都不知道是哪句话起的效果。5.3 从项目模板沉淀出个人方法用久了你会发现模板库最大价值不是那些具体命令而是它逼迫你思考一种“怎么跟 AI 协作”的方法论。每次你写一个模板都等于在回答三个问题这个任务的核心风险是什么AI 最容易在哪一步跑偏我要用什么方式把它拉回来这些问题想清楚了哪怕不用 Claude Code换成其他编程助手你也能很快搭出自己的模板体系。我现在已经把claude-code-templates里的思考方式迁移到了普通文档模板和团队内部 Wiki 上本质都是把“人脑里的标准操作”落到纸面。我的实际体会是模板库不是越厚越好而是越“准”越好。你的目标是让 AI 在 30 秒内进入状态而不是读十页说明书。那些能用一句话说清的硬边界优先放进模板那些需要情景判断的经验更适合由人去往上下文里临时补充。如果你刚开始建模板库不要想着一口气覆盖所有场景。从你最近一周反复让 Claude Code 做的三件事开始拆成三个模板跑通、记录、迭代。当一个模板的失败率连续两周为 0再考虑写下一个。这样慢慢长出来的模板库每一行都会带着你自己的判断力比任何别人分享的现成模板都更适合你的工作流。
Claude Code提示词模板库：让AI编程输出稳定可预期
如果你用 Claude Code 写过超过一个项目一定会有这种体会同一个提示词在不同目录下表现天差地别。不是模型不稳定而是你每次都在重新教育它。几个月前我把高频使用的提示词整理成了一套可复用的模板库文件名就叫claude-code-templates用 Git 管理从一个人用到后来拉进团队共用省掉的不只是反复打字的时间更重要的是让 AI 的输出质量和边界控制变得可预期。这套模板库本质上是一批预先写好的指令文件告诉 Claude Code 它是谁、要做什么、有什么限制、按什么格式输出。它解决的不是“写不出好提示词”的问题而是“同一个好提示词无法被重复使用”的问题。如果你被 AI 编程助手的自由发挥坑过或者想统一团队的代码审查、重构、测试口径又或者单纯想把自己的工作流固化下来这套思路都值得参考。下面我把设计思路、模板构成、落地实操和常见坑完整拆开讲一遍。这不是理论推演是我在真实项目里反复改出来的经验。1. 为什么我非要把 Claude Code 提示词沉淀成模板1.1 Claude Code 会话的“失忆”特性Claude Code 这类终端编程助手和网页版聊天最大的区别是它工作在一个会持续变动的项目上下文里。它会读目录结构、看文件内容、执行命令但这些能力同时也带来一个副作用每一轮对话其实都在重新建立上下文窗口。你可能会觉得自己已经在提示词里写得足够清楚了“你是一个资深 Python 开发帮我审查代码注意性能问题。”但换一个目录、换一个项目甚至过了半天再来它就把这些背景信息忘得干干净净。你自己也懒得每次敲一长串于是只能接受一个“泛泛而谈”的输出。这不是模型智商的问题而是没有给工作流加上“记忆锚点”。模板库解决的就是这件事把角色设定、行为约束、输出格式固定成文件让它每次被调用时都能精确加载。想通这一点后我立刻从“写提示词”转到了“写模板”。1.2 模板按什么维度分类才不踩坑早先我尝试把所有提示词塞进一个超大的CLAUDE.md后来发现这是个馊主意。文件越长模型注意力越分散可能你真正想强调的审查规则反而被边缘化。正确做法是按“任务类型”拆分而不是按“项目”整体写。我现在的模板库分四类你可以直接参考这种分法类型对应场景触发方式角色模板定义 AI 身份如后端开发、代码审查员、测试工程师放入.claude/commands/或手动引入任务模板具体操作如重构某个文件、补全测试、写提交信息命令式调用工作流模板多步骤串联如“改代码→跑测试→生成变更说明”组合多个命令或脚本规则模板项目通用约束如禁止改动生成文件、依赖锁定方式放入CLAUDE.md全局生效这个分类背后有一个重要原则角色和任务分离通用规则和临时指令分离。角色模板负责“我是谁”任务模板负责“做什么”规则模板负责“绝不能碰什么”。三者各司其职才能在复用时不被互相干扰。1.3 为什么选择文件化管理而不是记忆聊天有人会说直接在对话里跟 Claude Code.talk 一次它当场记住了不就行了确实可以但问题有两个。第一会话上下文有限聊了一会儿新指令就会把旧指令挤出窗口第二终端里塞一大段自然语言描述回头想复用还得翻历史记录既不可维护也不可审查。把模板落成文件等于给每个高频操作建了“标准操作卡”。团队新人来了不需要你手把手教他“我们公司审查代码要关注什么”他只要运行/code-review就能得到一套统一的审查框架。文件化管理还能放进 Git 做 diff让团队对提示词的改动都有据可查。2. 模板核心构成好的提示词模板长什么样2.1 角色、任务、约束、输出四件套我在反复迭代中总结出一条经验任何任务型模板只要包含四部分就会比随手写的一句提示词稳定得多。它们分别是角色role、任务task、约束constraints、输出格式output format。角色部分是让 Claude Code 切换到特定专家视角比如“你是一名有 10 年经验的后端架构师”。任务部分要写清楚边界比如“只审查这个 PR 涉及的 3 个文件”。约束部分最关键要明确禁止动作比如“不修改代码只输出建议”“不要触碰生成文件目录”。输出格式部分则统一了结果的形态让它每次都能生成可解析的列表或表格。这四部分的顺序也有讲究。角色放在最前面相当于给模型立一个“人设”后面的指令会天然靠向这个身份。任务和约束紧跟其后最后才指定输出格式。如果一开始就给格式模板模型会过于关注排版而忽略真正的分析任务。2.2 变量替换与上下文注入的两种方式模板如果只是死板的一篇文章复用价值会大打折扣。真正好用的模板必须有“插槽”。我常用的做法是两种命令参数注入和文件路径通配。在.claude/commands/下定义的命令文件可以通过参数提示引导用户输入文件路径或关键词。比如写一个review.md用户执行/review src/utils/parser.js src/api/client.js模板内部就能拿到这些路径作为待审查对象。另一种方式是让模板里写清楚“自动查找当前分支变化的文件”Claude Code 本身具备 Git 能力可以自己执行命令去定位变更范围。这里有个容易犯的错上下文注入不是越多越好。把整个项目的文件列表塞进模板会让模型陷入信息过载反而抓不住重点。我一般只注入两类信息一类是目标对象的路径另一类是本次任务的核心约束关键词。其余信息让模型按需去读文件。2.3 不同任务类型的模板写法差异同样是四件套写代码审查模板和写重构模板的侧重点完全不一样。审查类模板要把“禁掉什么”说死比如“不要自行修复只输出问题”因为审查场景最怕 AI 顺手改代码。重构类模板则恰恰相反要允许“修改代码”但必须要求“保持原有测试通过”。测试生成模板又是另一套逻辑它需要非常具体的输入输出示例因为模型的想象力太丰富了不给例子它就会编造不存在的接口。我写过的最小可用测试模板至少包含一个“被测函数真实调用方式”的示例以及“断言库选型”的硬性要求。这些差异本质上是任务风险模型不同审查怕越界重构怕破坏测试怕失真。模板的自定义要围绕“这个任务最怕什么”来写约束而不是通用地写一堆“请严谨”“请高质量”这种没人知道怎么执行的话。3. 实操从零搭建自己的 claude-code-templates3.1 目录结构与命名规范我的模板库目录结构长这样你可以直接抄claude-code-templates/ ├── CLAUDE.md # 全局规则描述模板库本身 ├── commands/ │ ├── review.md # /review 代码审查 │ ├── refactor.md # /refactor 重构指定文件 │ ├── test.md # /test 生成单元测试 │ ├── commit.md # /commit 生成规范提交信息 │ └── workflow-diff.md # /workflow-diff 双文件对比分析 └── scripts/ ├── parse_args.js # 解析复杂参数的小脚本 └── check_diff.sh # 获取当前 Git 变更文件命名规范我坚持三条全小写字母用连字符分隔单词动词开头。原因很实际Claude Code 的斜杠命令是大小写敏感的全小写能避免刚输入时切换大小写的中断感。动词开头则让命令在脑海里形成“动作”暗示比如我想要审查就会下意识敲/review。3.2 三个可直接复用的核心模板先看代码审查模板这是我最常用也最稳定的一份--- description: 审查当前分支变更的代码文件 argument-hint: 可选传入具体文件路径不传则自动查找 Git 变更文件 --- 你是一名资深代码审查工程师擅长发现潜在的缺陷、性能瓶颈和可维护性问题。 # 任务 审查指定的文件从正确性、性能、安全、可维护性四个维度分析。 # 约束 - 只审查用户传入的文件如果没传文件就通过 git diff --name-only HEAD 自动发现变更文件 - 不要修改任何代码只输出审查意见 - 不要审查生成目录、依赖文件、二进制文件 - 每个问题必须标记严重级别blocker / major / minor - 用中文输出但代码标识符保持英文原样 # 输出格式 ## 审查摘要 说明本次审查范围和整体结论。 ## 问题列表 | 严重级别 | 文件 | 行号 | 问题描述 | 修改建议 | ## 重点提醒 最多列 3 个最值得优先处理的问题。这份模板最核心的一条约束是“不要修改任何代码”。很多审查任务翻车就是因为 Claude Code 一看到问题就顺手 patch 了。把这句话钉在模板里输出边界立刻清晰很多。再看测试生成模板--- description: 为指定模块生成单元测试 argument-hint: 模块文件路径如 src/utils/date.ts --- 你是一名测试工程师精通 pytest、Jest、Vitest。 # 任务 为 {FILENAME} 中导出的每个函数/类编写单元测试。 # 约束 - 先读取被测文件列出所有导出对象 - 只写当前测试框架下可运行的用例不要引入额外依赖 - 每个测试用例必须包含 Arrange、Act、Assert 三段结构 - mock 只允许 mock 外部副作用不允许 mock 被测函数内部逻辑 - 如果被测函数有边界条件必须补充边界用例 - 输出为完整测试文件不要省略或写“略” # 输出格式 文件名{FILENAME}.test.ts 测试文件正文这个模板里“必须补充边界用例”那句非常关键不然 AI 会挑好写的路径测试空数组、空字符串、非法入参全给漏掉。重构模板我一般这样写--- description: 在不改变对外行为的前提下重构指定文件 argument-hint: 需要重构的文件路径 --- 你是一名专注于代码质量的软件工程师。 # 任务 重构 {FILENAME}提升可读性和可维护性。 # 约束 - 必须保持对外接口和函数签名完全不变 - 重构后运行项目现有测试确保全部通过 - 不改变任何业务逻辑只做结构优化 - 修改后输出一份简短的变更说明列出每个重构动作的原因 - 如果发现原有代码有潜在 bug在“附加发现”部分单独标注不要混入重构动作 # 输出格式 ## 重构动作 按文件修改点逐个列出。 ## 新增改动原因 解释每个动作解决了什么问题。 ## 附加发现 这里列重构中发现但未处理的潜在问题。这种写法的价值在于强制把“结构性改动”和“疑似 bug”分开避免模型把 bug 修复悄悄混进重构里让 diff 审查变得极其痛苦。3.3 如何让 Claude Code 自动加载模板模板文件不是放对了位置就会自动生效还需要理解加载机制。Claude Code 启动时会读取项目根目录的CLAUDE.md作为长期规则这部分对所有会话生效适合放项目通用约束。而commands/目录下的文件则作为斜杠命令被动态注册执行/就能看到命令列表。具体操作上我会把模板库里真正的“规则条款”抽到CLAUDE.md比如“禁止修改 public 目录下编译产物”“所有生成代码必须附带测试”。而任务型模板放进commands/。这样做的好处是规则始终在场任务按需调用不会出现一边强调不要动产物目录一边又在某个命令模板里让它“清理编译垃圾”的矛盾。如果你希望模板库跟着项目走就把整个模板目录放进目标仓库如果希望全局生效可以把它放到 Claude Code 的用户目录下让它成为跨项目的个人命令库。两种方式我都试过强烈建议先用项目级目录等沉淀稳定了再升级成全局配置。3.4 参数传递与命令调用的现场记录以代码审查为例实际操作中的调用方式两种都有。手动指定文件/review src/utils/date.ts src/api/client.ts自动发现变更文件/review自动发现依赖的是模板里“通过git diff --name-only HEAD自动发现”那句话。Claude Code 会执行这个 Git 命令解析变更清单像我在现场盯着它做了一遍又一遍最终效果是它能准确避开package-lock.json这类文件。参数解析有个需要留意的点如果你传路径时没加引号路径里有空格就会出问题。建议在模板描述里明确写一句“路径请用英文双引号包裹”。这不是模板代码的问题而是终端和命令解析共同决定的规则踩过一次后就刻在说明里了。3.5 模板驱动的完整操作流程这里按一次“提交前代码检查”的完整操作说说你能直观看出模板如何组合使用。第一步运行/review让 Claude Code 自动梳理当前分支变更输出问题清单。第二步把审查结果里的 major 问题挑出来运行/refactor src/module.ts让模型做定向重构。第三步运行/test src/module.ts补上缺失的测试。第四步运行/commit生成符合规范的现代提交信息。这四步每步都调用独立模板但因为上下文窗口还保留着前面的分析结果步骤之间不会丢失联系。整体看模板库不是让你一次性把所有事干完而是把“分析—重构—测试—提交”拆成有边界感的操作环节。边界感强了AI 出错的概率就低了出了问题也好定位。4. 模板库落地中的常见问题与排查技巧4.1 模板加载了但没生效最常见的现象是人明明在项目目录里敲了/review结果 Clude Code 回答“未找到该命令”。这时先别怀疑文件内容先看后缀名。命令文件必须使用.md后缀且文件名必须没有多余标点。我之前吃过亏的是把文件名叫review.template.mdClaude Code 认不出它。第二个原因是目录层级不对。只有.claude/commands/目录下的文件才会被注册为斜杠命令我最初放在.github/commands/里自然不生效。如果确实放在正确目录还是不识别检查文件首部是否有畸形的 YAML frontmatter。frontmatter 必须位于文件最开头且被两条---包裹中间不能有空行出现格式问题时模型会直接不认这个文件。4.2 指令冲突与上下文覆盖模板库变大后指令冲突是我的噩梦。典型情况是CLAUDE.md里写了“不要修改测试文件”但某个命令模板里又要求“如果测试缺失帮生成测试文件”。两条规则在同一轮对话里相遇模型往往更倾向遵循更具体的、离它最近的那条指令结果就把全局规则踩了。排查这类冲突的办法是用一个叫规则体检的脚本脚本式命令把每个模板中的约束条款提取出来人工看一遍是否有互相矛盾的关键词。我在模板库里加了一份conflict_check.md专门把“禁止”“不能”“必须”“不要”这些词列出来做统一审查。我的经验是任何全局规则在CLAUDE.md中只保留“不可谈条件”的底线比如“严禁删除锁定文件”所有可被任务覆盖的规则尽量下沉到具体命令模板。这样上下级规则之间就不会频繁打架。4.3 长输出被截断怎么办模板设置的输出格式太复杂时Claude Code 经常在生成一半时达到输出上限尤其是代码审查表格式输出几十个问题列下来很容易断。这里有两个解决方向。第一压缩输出格式。把“每个问题一行包含文件:行号:严重级别:建议”这种压缩格式作为默认选项把完整表格作为--verbose模式的选项。第二主动拆任务。在模板里写一句“如果问题数量超过 12 个先只输出 blocker 和 major 级别minor 级在最后追加”。防截断不能靠“让它快点写”要靠给模型一个可控的出口。我在审查模板里加了“先输出 summary再逐块输出列表”的顺序要求这样即使真的被中断前面的摘要也已经出来了损失可控。4.4 团队模板同步的版本管理模板库从单人到团队后最大的变化是“再也不能随手改文件”。因为每个开发者的使用习惯不同有人希望审查严格点有人希望更宽松直接就改模板会造成很大的混乱。我建议的协作方式是模板库独立成一个 Git 仓库所有模板的改动走 Pull Request保留两层审查一层是技术正确性一层是措辞清晰度。每次改动需要同时在命令描述和CLAUDE.md里同步更新避免命令改了说明文本还停留在旧版本。更新到项目里的方式用 Git submodule 或者构建脚本复制都可以。我倾向于用复制脚本把模板库同步到各个项目保留一个version.txt文件谁在哪个模板版本上遇到的问题就能快速定位。这样比所有人直接用同一个远端仓库更可控也不至于有人改了立刻影响到生产环境。5. 从模板到工作流再往前迈一步5.1 用变量和外部命令让模板“活”起来静态模板解决了“每次重复输入长篇大论”的问题但还没解决“让模型拿到实时数据”的问题。在一些复杂场景里我会让模板调用外部脚本来获取动态信息。比如在工作流模板里写# 任务 先运行 ./scripts/check_diff.sh 获取当前变更文件清单再基于清单执行审查。这样模板就不再是一篇静态提示词而是一个“能自己收集环境的智能工作流”。要注意的是让模板执行脚本时必须限定脚本路径不能让它手一滑去跑rm。我在所有涉及外部命令的模板里都会加一句“只允许执行项目根目录下scripts/文件夹中的脚本”并且每次执行前确认命令内容。5.2 模板效果度量与迭代模板不是写完就能一劳永逸的。我的迭代方法是给每个模板加了一个“失败信号列表”每当模型输出明显偏离预期就把当时的对话标记为一次失败案例按月统计哪些模板最常触发偏离。比如审查模板一开始没有“不要修改代码”的约束我统计到一个星期内它擅自改动代码三次。后来把这条约束写进模板偏离率立刻降下来。所以我的建议是不要凭感觉改模板先记录失败场景再用失败场景反推需要新增或调整的约束条款。迭代原则是“一次只改一个变量”。改完跑三个历史案例看输出是否更符合预期再决定保留还是回滚。模板库本质上是提示词工程而提示词工程最忌讳的就是一次堆一屏改动最后都不知道是哪句话起的效果。5.3 从项目模板沉淀出个人方法用久了你会发现模板库最大价值不是那些具体命令而是它逼迫你思考一种“怎么跟 AI 协作”的方法论。每次你写一个模板都等于在回答三个问题这个任务的核心风险是什么AI 最容易在哪一步跑偏我要用什么方式把它拉回来这些问题想清楚了哪怕不用 Claude Code换成其他编程助手你也能很快搭出自己的模板体系。我现在已经把claude-code-templates里的思考方式迁移到了普通文档模板和团队内部 Wiki 上本质都是把“人脑里的标准操作”落到纸面。我的实际体会是模板库不是越厚越好而是越“准”越好。你的目标是让 AI 在 30 秒内进入状态而不是读十页说明书。那些能用一句话说清的硬边界优先放进模板那些需要情景判断的经验更适合由人去往上下文里临时补充。如果你刚开始建模板库不要想着一口气覆盖所有场景。从你最近一周反复让 Claude Code 做的三件事开始拆成三个模板跑通、记录、迭代。当一个模板的失败率连续两周为 0再考虑写下一个。这样慢慢长出来的模板库每一行都会带着你自己的判断力比任何别人分享的现成模板都更适合你的工作流。
