我大概是在 Claude Code 刚支持项目级配置文件那阵子开始折腾 claude-code-templates 的。用了一段时间之后我意识到一个很现实的问题AI 编程助手确实能干活但每次让它干活之前我都得反复交代项目背景、代码规范、输出格式就像每次找同一个同事帮忙还得把前因后果从头讲一遍。直到我把这些“前因后果”全部沉淀成模板事情才真正顺起来。这篇文章不是理论科普而是我把 Claude Code 从“偶尔好用的聊天框”调教成“靠谱队友”的完整记录。内容包括模板的设计思路、目录结构、具体写法、踩过的坑以及可以直接抄作业的代码审查、重构、测试生成模板。适合正在用 Claude Code、但不满足于“问一句答一句”的开发者也适合想在团队里统一 AI 协作规范的人。1. 为什么要把 Claude Code 的工作流沉淀成模板1.1 我踩过的重复劳动先说我自己的场景。我手上同时维护一个支付网关服务和一个内部数据看板前者是 Java 17 Spring Boot后者是 Python 3.12 FastAPI。两套项目无论是技术栈、目录结构还是代码规范差异都非常大。早先用 Claude Code我每次要它帮忙写单元测试或者审查代码都得先来一大段背景说明“这是一个 Spring Boot 项目接口层在 controller业务逻辑在 service数据库访问在 mapper回调接口不需要校验签名返回结构统一是 ResultCode 加 data 字段……”“测试框架是 JUnit 5 Mockito测试类放在 src/test/java 下命名规则和被测类保持一致……”这种话第一次讲还有耐心第十次讲就真的很想抽自己。更麻烦的是如果哪次忘了说某个关键约束AI 给出的代码就会“很合理但完全不符合项目现状”比如拿 Mockito 生成了一个应该用 WireMock 的测试或者把 H2 当作生产库写进 apply 配置。后来我开始搜索 claude-code-templates 相关的做法发现不少人已经在做模板化这件事了。我的理解是把那些每次都要重复交代的“项目记忆”和“任务指令”变成固定的、可复用的文件。简单说就是给 AI 画一个框让它在一个相对确定的范围内输出。1.2 模板化的真正收益模板化带来的收益我用三个词概括一致性、启动速度、可积累。一致性最好理解。团队里五个人都用 Claude Code如果每个人都用自己的方式描述需求得到的输出风格一定五花八门。但用同一套模板之后输出结构就趋同了比如“先列问题再给修改建议”这个行为被模板固定下来AI 就不会动不动直接改代码。启动速度也很明显。以前开一个新对话光“喂背景”就得花三五分钟还得祈祷自己没漏说关键信息。现在项目根目录有CLAUDE.md和自定义命令模板新会话一打开AI 自己就知道项目是什么、规矩是什么、我通常让它干什么。我只需要填上这次任务的具体参数剩下的交给模板。可积累是我后来才感受到的价值。模板本质上是你对这个项目的理解沉淀。今天排查了一个诡异的 bug那就在坑清单里补一条明天发现 AI 总在某类输出上犯错那就改一下对应的命令模板。半年下来模板几乎就是一份活的“项目经验文档”比随手写的 README 实在得多。1.3 什么值得写进模板什么不值得也不是什么都往模板里塞。我总结了一个筛选标准高频、重复、有明确规则可循的事情才值得模板化低频、创意类、没有固定答案的事情不要模板化。值得的代码审查规则明确输出格式可以固定单元测试生成框架固定、目录固定、命名规范固定重构方案约束明确需要先方案后动工接口文档生成有固定的字段结构和描述要求新模块脚手架目录结构、依赖规范是现成的不值得的“帮我想个接口设计方案”——没有固定答案模板只会限制思路“解释这段代码在干什么”——需求太开放套模板反而别扭“我接下来三个月该怎么规划”——这不是任务级指令模板帮不上忙一句话模板是用来约束可重复流程的不是用来替代思考的。2. 拆解一套 claude-code-templates 的核心构成2.1 CLAUDE.md项目级的“长期记忆”Claude Code 有一个机制叫CLAUDE.md放在项目根目录每次会话启动时AI 会把它作为项目上下文读取。这个文件就是项目级的“长期记忆”。你可以把它理解成一本给 AI 看的《团队新人手册》我是什么项目、用什么技术栈、目录怎么分、有哪些规矩、有哪些坑。我现在的CLAUDE.md大概是这个结构# 项目概述 支付网关服务基于 Spring Boot 3 MyBatisJDK 17。 使用 Maven 管理依赖核心模块为 controller / service / mapper。 # 目录结构 - src/main/java/com/acme/gateway/controller接口层只做参数校验和响应封装 - src/main/java/com/acme/gateway/service业务层事务边界都在这里 - src/main/java/com/acme/gateway/mapper数据访问层禁止在循环中调用 # 常用命令 - 运行全部测试./mvnw test - 运行指定测试./mvnw test -DtestPaymentServiceTest - 本地启动./mvnw spring-boot:run # 代码规范 1. 对外接口统一返回 ResultT格式为 { code, message, data } 2. 业务异常使用 BizException禁止在 service 直接返回 null 3. 所有金额字段使用 BigDecimal禁止用 double # 常见陷阱 - local profile 使用 H2 内存库修改 schema 时注意兼容本地调试 - 对账任务依赖 Redis 分布式锁调试时不要手动加并发控制 - 第三方回调接口不校验签名内部接口必须校验签名这个东西最大的作用是让 AI 在“默认情况下”就具备足够准确的上下文。我不用每次说“我们的响应结构是 Result ”它看过 CLAUDE.md 就知道了。2.2 命令模板任务级的“执行规格”如果说CLAUDE.md是“长期记忆”那么命令模板就是“本次任务的执行规格”。Claude Code 支持把一些固定指令做成斜杠命令放在项目的.claude/commands/目录下比如.claude/commands/review.md。在会话里输入/reviewAI 就会读取这个文件按照里面写的流程执行。我把命令模板理解为“给 AI 的一份任务委托书”标题写清楚要干什么正文写清楚流程和边界条件。它解决的是重复脑力劳动比如“帮我审查这段代码”“给这个函数补测试”都可以做成命令。一个我自己写的命令模板会长这样请在开始之前阅读 CLAUDE.md 你的任务对 {{目标文件}} 做一次代码审查。 流程 1. 先阅读文件理解整体逻辑 2. 列出问题清单按级别分类严重 / 一般 / 建议 3. 对每个问题给出具体修改建议不要直接修改代码 4. 最后给出 3 行以内的总体评价 输出格式要求 - 使用 Markdown 表格 - 问题描述必须包含文件名和大致行号 - 修改建议要具体到代码层面不要只说“可以优化”模板里出现的{{目标文件}}就是变量我会在第 2.3 节详细讲。命令模板的好处是我把“怎么审查”这件事标准化了剩下的只有“审查哪个文件”一个变量调用成本极低。2.3 动态变量让模板可以“填空”变量是模板的灵魂。没有变量的模板是一篇死文档有了变量才变成一张可以反复填写的表单。我自己常用的是{{变量名}}这种占位符写法。调用的时候把真正的内容替换进去比如{{目标文件}}→src/main/java/com/acme/gateway/service/PaymentService.java{{测试框架}}→JUnit 5 Mockito{{被测函数}}→PaymentService.computeFee设计变量时我有一个原则能少一个就少一个。变量越多调用者要填的东西就越多模板的使用门槛就越高。一个模板如果超过三到四个变量我会重新考虑哪些信息其实是可以通过 CLAUDE.md 或默认值给定的。比如测试生成模板我只需要两个变量被测函数和测试框架。测试目录、命名规范、包名这些统统交给 CLAUDE.md 去管根本不需要塞进变量列表。2.4 模板怎么存放、怎么同步模板的存放位置直接决定它能不能被正确加载。我的习惯是放在项目仓库里用 Git 管理而不是随便扔在本机某个文件夹。推荐的结构是项目根目录/ ├── CLAUDE.md ├── .claude/ │ ├── commands/ │ │ ├── review.md │ │ ├── refactor.md │ │ └── add-test.md │ └── settings.json └── templates/ ├── service-impl.java └── rest-controller.javaClaude Code 会自动读取根目录的 CLAUDE.md 和.claude/commands/下的命令文件。templates/这个目录不是关键字它只是我用来放置“代码骨架”的地方配合命令模板里的“按照 templates/xx.java 的骨架生成代码”来使用。在团队里我建议把模板和项目代码一起走代码评审。谁改了模板都要说明为什么改改了之后对 AI 输出有什么影响。这样模板就会慢慢变成团队共识而不是某个人的私人配置。3. 设计模板的三个关键决策粒度、变量、默认值3.1 粒度太粗等于没写太细等于管死模板设计最难的其实是找粒度。太粗了没意义比如一个模板里只写“请重构代码”AI 根本不知道你希望它怎么表现太细了又管得太死比如“第一行必须写什么、第二行必须写什么”反而阻碍它发挥。我踩过一次很典型的坑。有一版代码审查模板我写了十几条检查项包括变量命名、注释规范、日志格式、异常处理、事务边界、性能风险、安全漏洞、兼容性……结果输出出来非常散AI 为了凑齐检查项把每个点都蜻蜓点水点评两句真正重要的设计问题反而没挖掘出来。后来我把粒度调整到“抓大放小”模板只圈定审查的维度不要求机器人式地逐项打卡。改成这样之后AI 的输出质量提升非常明显它会聚焦在逻辑错误、边界条件、数据一致性这些真正有价值的问题上而不是把时间花在“变量命名可优化”上。审查维度 1. 业务逻辑正确性条件分支是否完整边界情况是否覆盖 2. 数据一致性事务边界、并发控制、数据库读写顺序 3. 异常处理是否会把底层异常直接抛给上层是否吞异常 4. 安全性越权、注入、敏感信息泄露 5. 兼容性影响范围是否评估改动是否牵连其他模块这五条比之前十几条检查项实用得多。我的经验是模板的每一条规则都要能回答“这条规则阻止了什么常见问题”如果答不上来就删掉。3.2 变量每个占位符都要有存在理由前面说了变量要少这一节展开讲讲怎么筛选变量。我判断一个变量该不该存在的标准就一条这个信息是不是每次调用都不一定相同如果十次调用有九次填同一个值那它就不该是变量而是默认值或缺省配置。比如“测试框架”这个变量在同一个项目里几乎永远是 JUnit 5那就不如直接写进 CLAUDE.md 或模板默认值。反过来如果一个信息确定每次不同比如“目标文件是哪个”它就一定得是变量。还要注意变量的表达方式。{{目标文件}}比{{文件}}更明确{{被测函数}}比{{函数}}更不容易产生歧义。因为 AI 理解的依据就是变量名本身名字越具体替换时越不会跑偏。我自己整理过一个最小化变量清单的案例后面第 5 节会给出具体模板。3.3 默认值降低启动成本的关键默认值的意义在于让一个模板哪怕不填变量也能“跑起来”。我习惯在每个命令模板的开头定义一个“默认假设”区# 默认假设 - 测试框架JUnit 5 Mockito - 测试文件位置src/test/java - 命名规范被测类名 Test 后缀 - 代码风格遵循 Checkstyle 项目配置 如果你要调整以上默认值请在任务描述中明确指出。这样一个/add-test命令即使我偷懒不填任何变量它也会按“当前项目最可能的情况”给我生成测试代码。如果这次不是常规操作比如要给一个特殊工具类补测试我再补一句“改用 Testcontainers”就行。默认值的本质是“把高频情况写成兜底方案”。模板不是给 AI 看的最终还是给人用的降低使用门槛比增加功能项重要得多。4. 实操从零构建一套可复用的 Claude Code 模板4.1 第一步盘点你的高频场景不要一上来就写模板先盘一盘过去两周你让 Claude Code 干的都是什么事。我的盘点方法是翻历史会话记录统计出现频率最高的请求类型。我自己排出来的前三名是写单元测试频率最高代码审查次之小范围重构第三这三个正好都是有明确规则、流程清晰的任务天然适合做模板。我建议你也先从 2 到 3 个高频场景入手先把它们做到 80 分再考虑其他场景。一口气写十个模板大概率后面全吃灰。盘点的另一个产出是“规则清单”。回顾你平时在对话里反复强调的规则比如“不要直接在循环里调用 mapper”“接口返回统一结构”“测试要覆盖边界条件”等。这些就是你模板的第一手素材。4.2 第二步写第一版 CLAUDE.md写 CLAUDE.md 时有个原则先写现状和事实再写规范和期望。因为 AI 对“事实”的把握比对“期望”的把握更可靠。项目概述、目录结构、技术栈这些是事实必须先有代码规范、常见陷阱这些是期望和经验随后补上。第一版不用追求全面。我建议按这个顺序写项目一句话概述技术栈和关键版本目录结构说明挑重要的写不用列出每个文件常用命令测试、启动、构建代码规范前三条只写你最在意的写完之后做个简单验证新开一个会话直接问 AI“根据 CLAUDE.md这个项目的目录结构是怎么设计的”如果它能准确回答说明文件已经被正确加载了。常见的问题是写太长。我见过有人把 CLAUDE.md 写成上千行结果每次对话都要消耗大量 token 来读它反而影响效率。我的建议是控制在 100 到 300 行之间把那些“翻代码就能知道”的信息省略掉只保留“不写就一定会出问题”的信息。4.3 第三步搭一个命令模板并跑通它拿“代码审查”练手最合适。先在.claude/commands/下创建review.md内容参考第 2.2 节的模板。然后开一个会话输入/review src/main/java/com/acme/gateway/service/PaymentService.java注意这里我把变量直接跟在命令后面。如果 Claude Code 没有把这个参数识别为{{目标文件}}也可以在会话里进一步指明“本次审查的目标文件是 xxx”。第一次跑通后你会立刻感受到模板的威力AI 不用你再解释输出格式直接就按模板要求列出问题了。跑通之后要做一次“对照实验”同一个文件先在无模板状态下审查一次再用/review审查一次。两版输出对比往往能立刻看出模板的价值也能暴露模板里哪些指令写得不够清楚。4.4 第四步验证、迭代、版本管理模板不是写完就结束的需要持续迭代。我的迭代节奏是每用一周就回头检查一次凡是在对话里额外强调了模板没覆盖到的规则就补进模板凡是模板导致 AI 输出跑偏的规则就删掉或改写。版本管理方面我强烈建议给模板单独维护一个提交历史。比如在 commit message 里标注“review.md: 增加并发安全检查维度”这样几个月后你还能追查到某条规则的来龙去脉。团队协作时这个历史记录尤其有用它相当于模板的演进日志。还有一个小技巧在 CLAUDE.md 里加一个“模板变更记录”区块近期改了什么随手记上去。AI 读取后会知道当前模板是最新版避免它基于旧记忆行事。# 模板变更记录 - 2025-06-10review.md 增加并发控制审查维度 - 2025-06-18add-test.md 默认框架改为 JUnit 5 Mockito5. 实战示例代码审查、重构与测试生成模板5.1 代码审查模板先列问题再谈修改这个模板的核心决策是“先列问题再谈修改”。我见过很多 AI 审查代码时直接给出修改后的完整函数看起来很爽但风险很大它可能在没有完整理解上下文的情况下引入新的问题。而且一旦 AI 开始改代码就很少有人会再认真看那份问题清单了。所以我的模板强制要求“列出问题清单不要直接改代码”。这才是代码审查的正确姿势审查是发现问题和评估风险修改是后续单独的行为。完整的review.md模板请在开始之前阅读 CLAUDE.md 你的任务对 {{目标文件}} 做一次代码审查。 流程 1. 通读目标文件梳理核心逻辑 2. 按以下维度找出问题 - 业务逻辑正确性条件分支、边界值、异常路径 - 数据一致性事务、并发、读写顺序 - 安全性越权、注入、敏感信息 - 影响范围改动是否影响其他模块 3. 输出问题清单按级别分类严重 / 一般 / 建议 输出格式 | 级别 | 位置 | 问题描述 | 修改建议 | |------|------|----------|----------| 最后给出 3 行以内的总体评价重点说明最值得关注的一到两个风险点。 注意只做审查不要直接生成修改后的完整代码。5.2 重构模板一次一个方案先确认再动手重构比审查更危险因为它的破坏性更强。我踩过的坑是让 AI 直接重构一个函数结果它一口气改了三个关联方法还改了调用方测试也没跑最后我只能对着代码 review 半天。后来我把重构模板设计成“一次一个方案先确认再动手”这两条红线。模板要求 AI 先输出现状分析和重构方案等我确认了再写代码。这样既保留了 AI 的创造力又防止它自作主张扩大改动范围。完整的refactor.md模板请在开始之前阅读 CLAUDE.md 你的任务对 {{函数/方法名}} 进行重构。 第一步输出分析不写代码 1. 描述该函数当前行为输入、输出、副作用 2. 指出当前存在哪些问题可维护性、性能、可读性 3. 提出一个重构方案说明改动思路和影响面 4. 列出可能需要同步修改的关联代码 第二步等待确认 - 在我确认之前不要生成任何重构代码 第三步确认后执行 1. 按确认方案生成重构后的代码 2. 同时给出需要调整的关联代码清单 3. 运行 {{测试命令}}确认没有回归注意这个模板里的“第二步等待确认”用了明确句式。AI 对“不要动”这类指令的理解比对委婉的说法要可靠得多。写得直白一点执行偏差就少一点。5.3 单元测试模板让 AI 先出用例清单再写码写测试是最适合模板化的场景因为套路非常固定。我的模板有一个特色步骤先出用例清单再写测试代码。这是为了克服 AI 生成测试时“只覆盖 happy path”的老毛病。单独让 AI 写测试它往往给出一堆“返回正常结果”的用例边界条件和异常路径要么不写要么写得很敷衍。但如果我们要求它“先列清楚覆盖场景”模型就不得不把边界条件想一遍像空输入、超大值、依赖抛出异常、并发调用等场景都会暴露出来。完整的add-test.md模板请在开始之前阅读 CLAUDE.md 你的任务为 {{被测函数}} 生成单元测试。 第一步先输出测试用例清单不写代码 | 用例编号 | 场景描述 | 输入 | 期望输出 | 覆盖类型 | |----------|----------|------|----------|----------| 覆盖类型至少包含 - 正常路径 - 边界条件空值、极值、超长字符串 - 异常路径依赖报错、非法参数 第二步等待确认 - 确认用例清单后再生成测试代码 第三步生成代码 1. 使用 {{测试框架}}遵循项目测试规范 2. 测试类放在 {{测试目录}}命名与被测类一致 3. 每个用例对应一个独立的测试方法 4. 生成后返回测试文件的完整路径 注意不要修改被测函数。若测试中发现被测函数存在缺陷请在测试用例清单中标注不要直接改业务代码。这条“不要修改被测函数”的约束也很关键。AI 在写测试的过程中有时会“顺手”改业务代码来让测试通过这在测试驱动开发里是反模式。模板直接禁止掉。5.4 初始化脚手架模板让新模块也遵守规矩除了这三个高频模板我还有一个用于生成新模块脚手架的模板。它适合团队里技术栈统一、目录规范严格的时候使用。请在开始之前阅读 CLAUDE.md 你的任务为 {{模块名}} 生成一组代码骨架。 要求 1. 按照 CLAUDE.md 中的目录结构创建文件 2. 包括 Controller、Service、ServiceImpl、Mapper 接口与 XML 3. Controller 返回 ResultTService 接口定义业务边界 4. 每个方法注释标明输入输出不写具体实现逻辑 5. 不生成任何测试代码只生成骨架 文件清单列出将要创建的每个文件路径。有了这个模板新模块的代码风格就能和旧代码保持一致不用在代码评审时反复纠正“Controller 不要写业务逻辑”这种基础问题。6. 常见问题与排查技巧实录6.1 模板不生效先查这三件事模板没起作用的时候别急着怀疑 AI先按顺序排查三件事。第一件事是路径是否正确。CLAUDE.md 有没有放在项目根目录命令模板是不是在.claude/commands/下且后缀是.md路径写错了AI 根本读不到文件再怎么调提示词都没用。第二件事是是否被会话加载。Claude Code 的 CLAUDE.md 是在会话启动时读取的如果你在会话进行中改了文件当前会话可能不会立即感知。新开一个会话再试问题大概率会消失。第三件事是模板内容本身是否和其他指令冲突。比如你在同一段对话里既让它模板化输出又临时加了一句“不用按表格来”后一句的指令权重会覆盖掉模板设计。所以排查时要看看自己有没有在对话里加“私货”。我建议把这三条做成一个自查清单模板不生效时按顺序过一遍基本能解决九成的问题。6.2 输出质量忽高忽低多半是变量没填对如果你发现同一个模板有时候输出很好有时候输出很水那十有八九是变量替换出了问题。比如{{被测函数}}如果只是填了一个函数名没有给类名AI 就只能凭猜去找这个函数在哪可能找错甚至随便生成一个同名函数。我的经验是在模板里给变量加一些隐性约束让 AI 主动去确认请在开始前确认你已经定位到 {{被测函数}} 的完整路径和签名如果无法定位请先提问而不是继续生成代码。加了这句话之后AI 在不确定时就会主动询问而不是硬着头皮往下写。这个改动极大提升了测试模板的成功率强烈推荐加入。另外检查一下你填变量时是不是用了简称。PaymentService和com.acme.gateway.service.PaymentService.computeFee对 AI 来说信息量完全不同。变量填得越具体输出就越稳定。6.3 上下文窗口被模板占满怎么办这是很多人的痛点特别是那种把 CLAUDE.md 写得很长、命令模板又带了好几个大示例的情况。模板本身消耗 token如果代码量大AI 的注意力会平均分配到各个区块真正需要关注的任务反而不够用。我的解法是“按需加载”。在 CLAUDE.md 里只保留最核心的几行把详细规范拆到独立文件需要时通过引用加载。比如详细代码规范见 docs/code-style.md涉及代码审查时请阅读该文件的规范部分并遵循。命令模板里的长示例代码也一样不要全文塞进去用一句“参照 templates/xxx.java 的骨架”来引用。这样模板本身的体积小了留给实际任务的上下文窗口就大了。还有一个技巧在模板里明确“不需要做的事”。因为 AI 输出长文本也会消耗 token明确让它不要输出无意义的内容比让它多输出更符合这个场景的需求。6.4 多项目模板互相污染怎么隔离如果你同时在搞好几个项目很容易遇到模板互相污染的情况。最常见的就是上一个项目的 CLAUDE.md 被带到了下一个项目的会话里AI 拿着支付网关的规范帮你写数据看板的代码画面非常搞笑。解决办法是严格遵循“一项目一模板目录”的原则。每个项目根目录放自己的CLAUDE.md和.claude/目录不要把模板放在用户级目录里共享。如果确实有一段模板是跨项目通用的那也应该放在一个单独的公共文件里由各项目的 CLAUDE.md 通过引用而不是直接复制粘贴到每个项目里。我自己的做法是在CLAUDE.md第一行写明“本文件适用于 XXX 项目”如果 AI 会话上下文里同时出现多个项目的文件它有极大的概率能分清楚。再加一句“如果需求与该项目无关请先确认”防御效果更好。7. 收尾模板是活文档不是一次性配置写到这里我想说一个真实感受claude-code-templates 这件事难点不在“写模板”而在“持续维护模板”。很多人第一次搭好模板觉得大功告成然后几个月不碰等到 AI 输出开始跑偏才想起来看。其实模板就像代码一样是会“腐化”的。项目重构了目录结构变了规范改了如果模板没跟着更新那模板反而会变成错误的来源。我给自己定的规矩是每次被 AI 的输出坑到第一反应不是“下次对话说清楚”而是“是不是模板漏了一条规则”。如果是立刻补进去。这样一个个迭代下来AI 在项目里犯错的次数会越来越少。最后分享一个实用小技巧。我会在 CLAUDE.md 末尾维护一个“本周新坑”区块把自己近期踩过的坑随手记进去哪怕只是“下单接口的金额字段要用分而不是元避免浮点误差”。等 AI 输出变稳定之后再把那些已经不太会犯的坑内容移到“常见陷阱”或删除。这个方法让我每个迭代周期都能量化地感受到模板在变好也让我对“模板要长期经营”这件事有了真正的耐心。如果你正在用 Claude Code 却还没开始沉淀模板我建议今天就干一件事打开历史会话找出你上个月问得最多的三个问题把它们变成三个命令模板。做完这一步你大概就能理解为什么我说“先磨刀再砍柴”了。
