1. 为什么我会给 Claude Code 攒一套模板从一次差点翻车的重构说起先讲个真实经历。上个月我在一个中型项目里做模块拆分代码量不大但牵连很广涉及支付回调、任务队列、还有两块被历史包袱压着的遗留代码。我本来打算让 Claude Code 直接帮我梳理调用链、产出重构方案结果它表现得像一位记忆力只有五分钟的实习生——我上午刚确认过的接口依赖关系下午再问时它又给出了一套新的说法而且听起来同样自信。更折磨的是每次我让它“按刚才的思路继续”它都会重新组织语言甚至把某些我已否决的方案又捡回来。那两天我意识到一个事不是 Claude Code 不够聪明而是我压根没给自己定义“聪明”的标准。每次提问都在重新解释背景每次对话都在重建上下文它当然只能靠猜。于是我停下手里的活花了一整个下午把日常工作中高频出现的场景整理成了可复用的模板——后来我把这套东西命名为claude-code-templates。说句实话这套模板帮我的不只是一个项目它把我跟 AI 协作的方式从“聊一次算一次”变成了“有一套内部工作流”。这也就是这篇文章想和你聊的核心Claude Code 这类编程助手真正值钱的用法不是让它自由发挥而是用模板把它的输出框进一个稳定、可控、可复现的轨道里。它解决的是三个非常具体的问题上下文反复摩擦、回答口径漂移、以及每次开新任务时重复交代背景信息的低效。如果你也在用小规模团队维护中等体量的代码库如果你也受够了“AI 写出来的东西总差点意思”的挫败感那这篇文章应该能给你一些直接能抄走的东西。2. 模板不是提示词先搞清楚它到底管住了什么很多人一开始会把模板理解成“更长的提示词”这是第一个误区。提示词是一次性的输入模板是一套可被反复调用的行为协议。Claude Code 的模板系统至少可以管住下面四件事。2.1 命令入口把高频操作变成固定动作我在项目里放了一个.claude/commands/目录里面每一个 Markdown 文件都是一个斜杠命令。比如我在终端里敲/reviewClaude Code 就会加载.claude/commands/review.md按里面写好的流程走一遍代码审查。这是个非常朴素但极其有效的用法把“我要怎么交代任务”变成了“我要选哪个命令”。你不需要每次都写“请审查一下这次改动的代码重点关注安全性、边界条件和可维护性”你只需要敲/review。命令文件里把这些要求全写死了甚至还能规定它先读哪些文件、以什么顺序输出结论、哪些问题必须给具体行号和修改建议。对使用者来说这是个巨大的心智减负——你要思考的不是“怎么问”而是“这次是什么类型的任务”。2.2 角色和上下文让模型知道自己站在什么位置上除了命令.claude/agents/目录里还可以定义子代理模板。示例文件结构大致长这样--- name: backend-reviewer description: 专门审查后端改动关注事务、并发和存储层问题 tools: Read, Grep, Glob --- 你是一位资深后端工程师审查代码时必须先梳理数据流向再逐层检查 1. 接口层是否有参数校验 2. 服务层是否有事务边界 3. 存储层是否有索引和锁的隐患 4. 输出必须包含风险分级、问题定位、推荐修法这种角色模板的核心价值是让模型在动手前就建立一套“立场”。没有这个立场时它会默认用通用开发者的视角回答一切问题有了这个立场之后它看到同一段代码时会主动去找事务边界、索引和数据一致性问题——这正是你在特定场景下需要它做的事。2.3 记忆锚点把项目背景沉淀成可读取的文件模板里最容易被忽略但同时最值得花时间的是CLAUDE.md这类项目记忆文件。Claude Code 会在启动时读取这些文件作为长期上下文。我在里面记录的不是“这个项目用 React”这种废话而是开发过程中那些只可意会的约定这个项目的支付模块对金额计算采用分单位存储所有涉及元转分的操作必须走MoneyUtil数据库迁移脚本编号沿用YYYYMMDD_xxx格式禁止使用语义命名测试命名里should_前缀表示行为驱动用例test_前缀表示纯单元用例历史遗留代码LegacyService里的方法不允许直接改动签名只能加 override。这些内容如果不用文件沉淀每次对话都要重新说一遍就算说了模型也容易在长篇对话中丢失。放进模板之后它就成了每次任务启动时的“岗位手册”可靠性完全不一样。2.4 输出格式把自由发挥的空间收窄模板还需要管住输出的形态。一份审查报告的模板里我会明确要求“按照 [风险等级] [文件路径] [问题说明] [建议改法] 的格式逐条输出”并且要求“如果未发现问题明确写无不要重复代码内容”。这种看似生硬的格式要求实际上是在对抗大模型最麻烦的两个毛病废话太多、结论模糊。我自己用过一个小技巧在模板末尾加一句“在给出方案前先列出你未验证的假设”。这一句话就能让模型从“直接给答案”切换成“先确认边界”输出质量提升非常明显。3. 攒一套能用的模板目录结构、变量语法和加载机制模板系统要落地需要先把地基打牢。我建议按照下面的目录结构组织一个独立仓库来管理这套配置这样既能版本管理也能在多个项目里复用。3.1 我实际使用的目录结构claude-code-templates/ ├── .claude/ │ ├── CLAUDE.md # 全局项目记忆放通用的协作规范 │ ├── commands/ │ │ ├── review.md # /review 审查改动 │ │ ├── refactor.md # /refactor 生成重构方案 │ │ ├── test.md # /test 生成单元测试 │ │ ├── docs.md # /docs 生成接口文档 │ │ └── handover.md # /handover 生成交接文档 │ └── agents/ │ ├── backend-reviewer.md # 后端审查子代理 │ ├── frontend-architect.md # 前端架构子代理 │ └──>--- description: 审查指定文件或目录的代码质量 argument-hint: [文件或目录路径] --- 现在审查 {{file_or_dir: 未指定}} 执行步骤 1. 先用 Grep 找到相关引用理解本次改动的调用方 2. 再用 Read 按顺序读取文件内容 3. ...不同版本对变量的支持会有差异有的用$ARGUMENTS直接拿整段参数有的支持命名变量和默认值。我在实际使用时会更保守一点优先用 positional 参数实在需要复杂结构时直接要求用户在命令后跟一个 JSON 对象模板内部自己解析。这里给你一个可参考的写法--- description: 按指定规则生成代码 argument-hint: {task: 描述任务, lang: 目标语言} --- 你的任务{{task: 未指定}} 目标语言{{lang: TypeScript}}3.3 加载优先级和文件放置一个容易踩坑的细节Claude Code 对配置文件的加载有一定的优先级和合并机制项目级别的配置会覆盖用户级别配置CLAUDE.md的内容会作为长期上下文自动加载而commands/和agents/里的文件只有在被调用时才会进入上下文。这是个很重要的区别——不要把所有指令一股脑塞进 CLAUDE.md否则每一个任务都会背着臃肿的上下文既费 token 又稀释注意力。我见过一个团队把整个团队的开发规范写进了全局 CLAUDE.md结果模型在写一个简单的工具函数时也要先思考“换行符使用 LF 还是 CRLF”“缩进到底用几个空格”这种和任务无关的负担。后来我把规范按主题拆散到各自的命令模板中问题立刻缓解。经验是全局文件放协作底线和代码风格底线具体场景的详细要求放到对应的命令模板里。安装到目标项目时我一般用脚本做一个符号链接而不是复制文件。好处是模板仓库更新后各个项目能同步拿到最新版本不用手动逐个同步。# scripts/install.sh #!/usr/bin/env bash set -euo pipefail TARGET${1:-.} TEMPLATE_ROOT$(cd $(dirname $0)/.. pwd) mkdir -p $TARGET/.claude/commands $TARGET/.claude/agents ln -sfn $TEMPLATE_ROOT/.claude/CLAUDE.md $TARGET/.claude/CLAUDE.md for f in $TEMPLATE_ROOT/.claude/commands/*.md; do ln -sfn $f $TARGET/.claude/commands/$(basename $f) done for f in $TEMPLATE_ROOT/.claude/agents/*.md; do ln -sfn $f $TARGET/.claude/agents/$(basename $f) done echo 已安装到 $TARGET/.claude4. 三块真正值得抄的模板审查、重构和交接目录结构懂了、语法会用了最关键的还是模板内容本身。下面三块是我日常使用频率最高、收益最明显的直接把骨架给你细节你按自己团队情况调。4.1/review代码审查模板治住模型的“客套话”我早期让 Claude Code 审查代码时它经常输出“整体质量不错但建议优化命名”这种说了等于没说的废话。后来在模板里加了非常硬的要求不许评价整体只许列问题问题必须带行号和严重级别。--- description: 对当前改动进行严格代码审查 argument-hint: [可选: 文件或目录默认为 git diff] --- 请按审查员模式工作不要客套不要写总体评价。 审查范围 - 如果提供了参数以参数指定的路径为准 - 否则分析 git diff --stat 和 git diff 标出的改动内容。 必须执行的动作 1. 先用 Grep/Glob 找出依赖这些代码的外部调用方 2. 再阅读文件完整内容而不是只看 diff 片段 3. 对每一处问题输出 - [关键]会导致线上故障或数据错误 - [重要]会引发部分场景异常或存在明显边界漏洞 - [建议]可维护性、命名、可测试性改进 禁止事项 - 禁止输出“整体不错”“建议继续保持”之类的评价 - 禁止重复代码内容只说明问题 - 如果没有发现问题直接输出“PASS”并给出你已检查的维度 最后附一行你本次审查未覆盖到哪些文件或场景。这个模板真正厉害的地方在最后一行——逼模型自己交代盲区。有了这句话模型的“自信”就收敛了它会明确告诉你“我只看了 service 层controller 和 repository 还没覆盖”你也就知道下一步该补什么了。4.2/refactor重构计划模板让 AI 先写计划再写代码重构是最容易失控的场景。模型很容易在“改着改着”的时候顺手把一个不该动的函数也改了。我的办法是强制它先输出重构计划并且计划必须先通过你确认它才能写代码。--- description: 生成一份可执行的重构方案 argument-hint: [重构目标描述] --- 当前任务 {{refactor_goal: 未指定}} 第一步分析现状不写代码 - 梳理涉及的模块、入口、出口、依赖关系 - 列出“改动危险信号”公共函数兼容性、序列化结构、数据库字段 - 按照影响范围输出一个模块清单 第二步给出迁移策略 - 明确步骤顺序标注每步完成后的可验证状态 - 对每个模块标记安全改动 / 危险改动 / 禁止改动 - 如果某一步可能破坏现有测试必须提前说明 第三步等用户确认 - 在你展示完上述内容后必须停顿并询问是否继续 - 用户未明确回复“继续”之前禁止修改任何文件 第四步执行 - 一次只改一个模块 - 每完成一个模块运行与该模块相关的测试并汇报结果 - 任何超出计划的改动先停下来说明原因再处理一次只改一个模块、每步必须有可验证状态这两条是重构模板的核心。它把“大重构”拆成了一串小步的“安全运行”我从那以后再也没出现过模型大改一通然后把全局状态搞崩的情况。4.3/handover交接文档模板把“藏在大脑里的上下文”搬出来交接文档是我个人收益最大的模板。团队里最怕的不是代码烂而是某块代码的知识只在某个人脑子里。模型虽然看不到人的大脑但如果你让它通过代码反推上下文然后把结果结构化地写下来交接效率能提一个档次。--- description: 为目标模块生成交接文档 argument-hint: [模块路径或入口文件] --- 请生成一份面向新接手开发者的交接文档目标读者是“完全不了解此模块的人”。 结构必须包含 1. 模块职责这个模块解决什么问题输入和输出是什么 2. 核心流程用文字描述主调用链路标注关键状态流转 3. 数据模型涉及哪些数据结构、字段含义、存储位置 4. 外部依赖依赖了哪些其他服务、队列、第三方接口 5. 已知坑点从代码里推断出的常见陷阱例如 - 隐藏的时序问题 - 必须按特定顺序初始化的资源 - 看起来像 bug 但实际上是故意为之的行为 6. 改动指南新增需求时通常需要触碰哪些文件不能动哪些文件 输出要求 - 禁止泛泛而谈每个结论都要标注对应的文件路径或函数名 - 无法从代码中确认的部分明确标注“需要原负责人口头确认” - 全文长度控制在 800 字以内密度优先这里面“代码推断 需要人工确认”两张表非常关键。模型从代码里能挖出七成上下文剩下三成它会很诚实地标记为待确认这样新接手的人就不会把“未知”当成“本来就这样”。5. 我在实战中踩过的坑模板写得太“理想化”会翻车模板这东西写起来很爽用起来才会暴露问题。我踩过的坑大致有这几个列出来你避免就好。5.1 陷阱一模板里写了模型做不到的事最早我给审查模板写过一个要求“请检测所有可能导致 SQL 注入的路径”。模型确实会很快地回复“未发现注入风险”。但是它并没有真正模拟不同的输入和编码路径它只是从代码模式上大概判断了一下。后来我在模板里把“可能导致”改成了“请列出外部输入到达 SQL 查询的所有路径并逐条说明是否经过参数化”限定到具体路径追踪模型才能真正做到位。模板里的要求必须是模型能力范围内的、可被验证的、有明确操作步骤的否则就是一句空话。5.2 陷阱二参数太多命令变成了“写作文”我早期设计的命令模板有的甚至要填八个参数。真实用的时候根本没人愿意填最后大家都直接用最原始的自由对话。后来我给自己定了个规矩**一个命令最多接受两个参数超过两个就拆成子命令或者在运行时让模型通过提问来收集信息。**比如/docs命令只需要传一个模块路径其他细节全部让模型自己通过阅读代码来获取效果反而更好。5.3 陷阱三模板版本和项目代码脱节模板仓库在维护项目代码也在演进两者很容易错位。比如我在模板里写“找到OrderService并分析订单状态流转”但项目重构后该类已经改名模板就会失效而且模型不会主动告诉你“这个模板引用的类已不存在”它会假装按旧名字处理输出自然失真。我现在习惯在每个命令模板的头部加一行“前置检查”1. 确认 模块路径 指向的文件或目录存在不存在时立刻停止并报告 2. 确认命令中引用的关键类名、表名、函数名在代码库中可被检索到 3. 以上检查通过后才开始正式任务这行“前置检查”看起来很笨但它能避免模型带着错误假设开工也能让你在模板失效的第一时间发现而不是等到输出结果不对时再去排查。5.4 陷阱四把模板当教条忘了模型可以带温度还有一个容易被忽略的问题模板会把模型的自由度收得很死导致它在遇到超出模板范围的意外情况时不知如何处理。比如审查模板要求只按 [关键/重要/建议] 输出但模型发现了一个“必须重构整个文件才能解决的问题”它可能不会主动提出来因为模板没给它这个出口。解决方案是在每个模板的末尾固定加一句话“如果任务过程中发现模板无法覆盖的严重问题直接说明并跳出当前模板流程。”这不是妥协而是给系统留一个“熔断机制”防止模板本身成为盲区。6. 模板的协作化和维护节奏一个人的效率工具怎么变成团队的基建等到模板在你的个人工作流里跑顺了下一步自然是把它分享给团队。但“分享”这件事如果只是扔一个仓库链接大概率第二天就没人用了。这里有几个我实测出来的协作方式。6.1 模板仓库也要走代码评审我把模板仓库当作正式的代码仓库来维护每次修改都要提 PR、都要有描述、都要过一遍 review。理由是模板直接影响所有成员的日常效率一次错误的模板改动比一次错误的产品代码改动影响面更大。比如有人把 review 命令里的“必须检查 SQL 注入”改成“可选检查 SQL 注入”就意味着下一次线上事故前的审查里少了一道关卡。这种事不能凭感觉乱改。6.2 模板的价值要配合一个“记录提炼”的习惯模板不是一次写完的它需要在真实使用中持续迭代。我会在每次“觉得模型输出不对劲”的时候把当时的对话上下文固定下来——不是存整段聊天记录而是提炼成一条规则补丁。比如某次模型在审查时忽略了一个只在生产环境才会触发的分支我就给 review 模板加了一行“分析分支覆盖时必须检查生产环境配置与本地配置的差异。”这个习惯坚持三个月模板的“含金量”会明显提升。6.3 验收标准新成员能不能只靠模板完成一个任务最后分享一个我用来评估模板质量的标准**找一个完全不了解本模块的新成员只给他模板和代码库看他能不能独立完成一次代码审查并输出合格报告。**如果做不到问题不一定出在这个人身上更可能是模板里漏掉了很多“默认你懂”的信息。我第一次这样测的时候发现自己写的模板默认了新同事知道项目的目录结构、知道哪几个模块是核心、知道发布流程——这些全都没写进去。补上之后模板的通用性才真正立住了。模板这东西确实存在一个投入产出比的拐点前期整理会很费时间但一旦达到某个复用次数它的边际成本几乎为零而每次调用都在帮你省钱。**别追求一次写得多完美先跑起来再在真实任务里不断补丁迭代。**等到你某天发现自己遇到一眼就能判断出“该用哪个命令”的问题时说明你已经把 AI 协作从“随机聊天”升级成了“标准作业”了。