上个季度给一个微服务项目补单元测试我对着同一个终端里的Claude Code连续问了三次“给这个模块写测试”三次回答风格完全不一样第一次用了JUnit 5的ParameterizedTest第二次用的是Mockito原生写法第三次把断言库换成了AssertJ。模块还是那个模块需求还是那个需求但AI的输出像三个不同的人写的。排查了半天才发现问题不在模型而在我——我从来没有告诉过它这个项目的测试规范、依赖版本、代码风格和红线约束每次都在靠临场发挥。后面我开始着手整理一套自己的claude-code-templates把高频任务的项目背景、输出规范、避坑约束全部固化下来。效果立竿见影同一个任务的回复风格基本稳定了我在代码审查上花的时间少了三分之一。这篇文章就是这段时间的完整复盘里面包含了我的目录结构、模板写法、踩过的坑以及团队复用时的版本管理思路适合重度使用Claude Code、正在被“输出不稳定”困扰的开发者参考。1. 为什么我最终转向了claude-code-templates这种“预制菜”模式1.1 直接对话的三个坏味道遗忘、漂移、重复劳动先说最直观的问题上下文遗忘。Claude Code的对话窗口有上下文上限哪怕没到上限聊到后面它也会“选择性失明”。我经常遇到的情况是聊到第三十个来回的时候它已经忘了项目用的是Spring Boot 3.2而不是2.7忘了数据库迁移脚本必须放在db/migration目录下甚至忘了我开局说的“不要动公共模块”。这不是模型的智力问题而是信息管理问题。你想想人开会也要先宣读会议纪要和项目背景不可能每个新同事来都从零开场。AI也一样它需要一份“入职文档”。然后是风格漂移。同一个任务今天早上问和下午问结果能差出两个档次——早上它规规矩矩按你上次的反馈改下午它又开始“自由发挥”。我最后总结出一个规律只要对话是靠临场措辞描述的输出质量就必然依赖你当时描述得有多细致、多巧。这不是玄学是概率。你把条件写清楚了它的采样空间就小了结果自然更稳定。最后是重复劳动。每个新任务都要重新交代技术栈、目录约定、提交规范、禁用词列表。写一个模板之前我每开一个任务都要先粘贴一大段背景说明少则两三百字多则上千字。这些字打完心态已经累了一半。1.2 模板的真正价值把隐性约束变成显性输入那有人会问直接写一个巨型提示词不就行了不行。提示词是一次性的写在对话里它会被后续内容淹没换个会话就没了。而 claude-code-templates 的价值在于把提示词变成了仓库里的持久资产。具体来说它做了三件事固定变量技术栈版本、目录结构、命名规范、错误处理偏好这些东西写成模板之后每个会话开局就注入不需要重复输入。固化约束哪些代码不许写、哪些目录不许动、哪些库不许引入直接写死在模板里AI跑偏的时候能拉回来。沉淀最佳实践你上一次发现“这个项目的异常处理应该用业务异常而非通用Exception”写进模板后下一次它就会默认遵守。换句话说模板是给Claude Code的“企业文化手册”。AI本身不懒它只是不知道你的规矩。你把规矩写清楚它就能照着办事。这个转变让我从“每次对话都要当项目经理”变成了“写一次模板、长期受益”。2. 一套可落地的模板仓库应该长什么样2.1 CLAUDE.md挂在项目门口的“永久记忆”Claude Code原生支持项目级的CLAUDE.md文件放在项目根目录每次会话启动时它会自动读取这个文件作为背景上下文。这是整个模板库的地基我所有的项目模板都会从这里开始。我自己的CLAUDE.md结构固定在五个段落后来发现这个结构对大部分技术项目都适用项目概览与技术栈两三句话说清楚这是什么项目、用什么语言、关键依赖版本。目录结构与职责边界哪个目录放什么、哪个模块是核心、哪些改动必须先通知相关负责人。代码规范与命名约定包名怎么起、接口怎么命名、提交信息格式。禁用与红线不许引入什么依赖、不许直接改哪张表、不许可用哪些被废弃的API。高频命令构建命令、测试命令、lint命令、单测单跑的快捷方式。举个例子一段我实际用过的CLAUDE.md片段# 项目记忆每次会话自动加载 ## 项目概览 - 结算服务settlement-serviceJava 17 Spring Boot 3.2.x - 主要负责账单生成、对账、差错处理依赖 payment-client 与 accounting-core ## 目录约定 - 业务逻辑放在 domain/ 下不要写进 controller/ - 数据库迁移脚本放 db/migration/按日期命名V20240101__xxx.sql - 外部接口适配放 adapter/ 下禁止在 service 里直接调第三方 SDK ## 代码规范 - Controller 只做参数校验和响应包装一律走 Service 层 - 异常统一抛 BizException(code, msg)禁止裸抛 RuntimeException - 提交信息格式feat|fix|refactor|test: 简短描述 ## 禁用与红线 - 禁止新增对 legacy-db 的直接 JDBC 访问统一走 settlement-mapper - 禁止在事务内调用远程 RPC容易长事务 ## 高频命令 - 全量单测mvn test - 单测单个类mvn test -DtestOrderCalculateTest这个文件写完之后最大的变化是新会话不再需要我重复说明“项目是干嘛的”它自己就知道。CLAUDE.md就是给Claude Code的入职手册值得花半小时认真打磨。2.2 斜杠命令高频任务从十句话变为一条命令CLAUDE.md解决的是“全局背景”但具体到某个高频任务比如“写接口文档”“补单测”“代码审查”你还需要一套更聚焦的任务模板。在Claude Code里这对应slash command我放在.claude/commands/目录下每个文件是一个Markdown命令。我维护过的最实用的几个斜杠命令/review让AI按项目的代码规范审查改动输出问题清单和修复建议。/test为指定的类生成单元测试要求模拟边界条件和异常分支。/doc给指定的接口或模块生成文档按团队模板输出。/refactor在不动公共接口的前提下优化代码结构必须列出改动影响面。每个命令文件的结构也很简单头部放YAML frontmatter写命令元信息正文是具体指令。例如/test命令--- description: 为指定类或模块生成单元测试 argument-hint: 类名或模块路径 --- 请为 $ARGUMENTS 生成单元测试遵守以下要求 1. 测试类放在 src/test/java 下包名与被测类保持一致 2. 优先使用 Mockito AssertJ禁止引入新的测试框架 3. 必须覆盖 - 正常路径happy path - 参数为空/越界的边界情况 - 业务异常分支BizException 的 code 和 message 4. 测试方法命名方法名_场景_预期结果如 shouldCalculateSuccess_WhenValidOrder_ReturnAmount 5. 最后检查一遍测试必须能独立运行不依赖本地环境变量或外部服务这套东西的价值在于把每次都要口述的长指令压缩成了两条斜杠。我实测过写交互式提示词的时候同样的要求我能打出两百字但写成/test 订单服务之后AI执行的就是一个结构完整的任务质量稳定很多。2.3 子代理模板把“无所不能”拆成“各司其职”Claude Code还有一个我很喜欢用的机制子代理subagents。它的作用是让AI以专属角色并行处理子任务每个角色有独立的系统提示和工具权限。我把它也纳入模板体系放在.claude/agents/目录下。我项目里长期维护过的子代理角色有三个code-reviewer只读代码分析潜在Bug、安全隐患、性能问题输出裁剪后的建议清单。test-writer只能写测试代码不能动业务代码。它的权限是有限的这反倒能避免AI顺手改业务逻辑。doc-writer专门把代码改动整理成可读性强的文档输出给非技术同事看。每个子代理文件就是一个带YAML frontmatter的Markdown文档写明角色名称、职责描述、允许调用的工具。例如--- name: test-writer description: 专注于生成高质量单元测试绝不修改被测业务代码 tools: Read, Grep, Test, Write --- 你是一名测试工程师任务是为指定模块编写单元测试。你只允许新增或修改测试文件禁止修改 src/main 下任何业务代码。如果发现业务代码存在问题把它记录在最终报告的“发现的业务问题”一栏等待人工处理。子代理最大的好处是角色隔离。以前我一个人让它“先写代码再补测试再审查”它经常在写测试时顺手改了业务代码。拆成多个角色模板之后每个角色只看自己的工作边界越权的情况少了很多。3. 从零搭建模板库先钉死高频重复场景3.1 第一步复盘你一周内反复做过的事情很多人一上来就闷头写模板结果写了几十个能用上的没几个。我的建议是先复盘再动手。打开你的终端历史和IDE使用记录翻出过去一周的对话记录统计一下哪些事情你反复在做。我当时的统计结果大致是这个分布任务类型一周出现次数单次耗时写/补单元测试14次15-30分钟接口文档生成9次10-20分钟代码审查自己改完让别人看8次10-25分钟重构旧代码6次30-60分钟排查线上日志/异常5次20-40分钟这个列表就是模板库的索引。排序靠前的任务优先做模板靠后的可以先不碰。用真实频率决定优先级比拍脑袋规划靠谱得多——至少我后来不会再因为“我可能用得上”写一些僵尸模板。3.2 第二步写第一个模板时死磕的五个要点模板和提示词不一样它要承载“长期使用”的重量。我写第一个模板反复改了七八版最后总结出五个要点缺一不可。要点一给出负面清单Dont比追求正面指令更重要。你告诉AI“要做什么”它总能理解几分但你要是不告诉它“不许做什么”它大概率会在某个边界上踩线。比如写测试模板我特意加了“禁止引入新的测试框架”“禁止修改被测类”这两条防住了大部分失控操作。要点二输出格式一定要显式约束。人和AI协作最大的成本其实是“读它的输出然后改”。如果模板里不指定输出格式AI会自由发挥成一大段叙述文字指定格式之后比如“问题清单用表格、每条必须包含优先级和修复建议”它的输出就变得可以直接粘贴进工作流。这件事在第四个章节里我会展开讲。要点三预设变量而不是写死内容。模板要能复用必须留参数位。我的斜杠命令都用了$ARGUMENTSCLAUDE.md里则用路径占位符比如module-name。宁可模板里多几个占位符也不要写得太具体导致换个项目就要改一半。要点四给AI留出“提问/确认”的通道。模板不是把人锁死而是给AI一个“拿不准时怎么办”的出口。我常用的做法是在模板末尾加一段“如果以上要求有任何与项目实际情况冲突的地方请指出冲突点并暂停执行等待用户确认。”这避免了AI不问就乱干的尴尬。要点五写完后用三个真实场景试跑一遍。模板看着顺眼不算数拉一个真实任务跑一遍才算数。我自己有个固定流程写完模板后连跑三个任务只观察一件事——AI的输出质量是不是优于我临场写提示词的结果。如果不是就改模板再试。3.3 第三步用真实项目迭代而不是凭空设计我必须强调模板是迭代出来的不是设计出来的。我最开始为“接口文档”写了一个自认为很完整的模板实际用了两次就发现两个问题一是它要求的输出结构太细AI为了填结构反而忽略了内容的准确性二是它没考虑到“接口文档需要同时输出给前端和后端两拨人”这事导致模板里的术语两边都不满意。后来我把文档模板砍掉了三分之一的内容改成两段式输出一段给前端请求参数、返回示例、错误码一段给后端实现细节、边界条件、依赖关系。跑了几周才稳定下来。我更推荐的做法是把模板当成代码对待每次使用后顺手记一笔“这次哪里不对劲”攒够问题就改一版。这在工程上叫“小步迭代”用在模板上完全成立。一套成熟模板从来不是一次写成的而是十几次使用后打磨出来的。4. 模板真正好用起来靠的是这几个细节4.1 输出格式约束比内容描述更重要这是我从大量试错里得到的最反直觉的一条经验。刚开始我写模板精力全放在“描述任务内容”上比如“请重构这个模块并保持功能不变”结果AI输出了一大段“这是一个很重要的模块经过分析我建议……”的废话——它把重构过程写成了汇报材料我没法直接用它。后来我改了模板把重点放在输出格式上。同样的重构任务我要求它按三段式输出第一段“改动摘要”最多三行第二段“改动文件清单”含每个文件的改动描述第三段“风险点”列出可能影响的范围。改完之后AI的输出立刻变得“能干活”了。给一个我实际用的输出格式模板片段## 输出要求 请严格按照以下结构输出不要添加开头结尾套话 1. 原问题定位一句话说明当前代码存在的问题 2. 修改方案表格文件 | 改动点 | 影响范围 3. 验证方式你打算怎么测试这次改动命令是什么这个细节的核心逻辑是AI很擅长填空但不擅长猜你想要什么格式的答案。你把格式作为模板的最高优先级它就会把精力留给真正的问题。4.2 变量注入不要在每个模板里硬编码模板库建到中期我遇到一个尴尬的情况一共有十几个模板文件每个文件里都写了同样的三行项目背景技术栈、目录约定、红线段落。结果项目升级了一次Spring Boot版本我要改的地方是十五个文件而不是一个。这就是硬编码的代价。我的解决方案是层级化拆分配置。CLAUDE.md里放全局信息斜杠命令里只引用任务本身的要求不重复背景。如果某个任务必须知道技术栈我让命令里用$ARGUMENTS接收参数或者直接写“技术栈信息见CLAUDE.md”。这样做的另一个好处是如果你同时维护多个项目比如一个Java微服务和一个Python脚本仓库你的斜杠命令模板可以共用只有CLAUDE.md不同。我的.claude/commands/目录已经做到了跨项目复用这全靠变量和引用而不是复制粘贴。4.3 与MCP工具链联动时的三个注意事项Claude Code支持MCPModel Context Protocol可以用它把内部API、数据库、监控平台等接进对话。模板和MCP联动时我踩过几个坑值得单独说一下。第一个坑模板里设计的步骤假设了工具可用但实际没接。写模板时觉得“反正可以调测试平台”结果在不通MCP的环境下这个模板直接半路卡住。后来我每个模板开头都加一条“如果下列工具不可用请跳过相关步骤并明确告知”模板立刻变得健壮。第二个坑工具权限过大。MCP可以集成数据库查询、文件写入、甚至线上配置发布这给模板带来了风险。我在模板里明确约束了工具的调用边界比如“只允许调用只读查询接口禁止调用变更类接口”。这条约束不能只靠AI自觉最好配合工具侧的权限配置双保险。第三个坑MCP返回的数据格式不稳定。有时候MCP返回JSON有时候返回Markdown表格模板里的后处理逻辑就会失效。我的做法是在模板里要求“所有MCP返回的数据先整理成统一格式表格再做下一步分析”。多花几秒钟整理能省掉大量后续纠错。4.4 危险操作兜底模板里必须有红线模板是为了让AI做得更好但也意味着你会把更多权限交给它。这时候模板里必须写清楚“什么不能做”。我把这个叫红线条款每一个涉及文件修改或命令执行的模板里都有。我在CLAUDE.md和命令模板里固定保留了这几条禁止直接删除代码文件除非用户明确同意禁止修改依赖版本号升级依赖必须人工做禁止在模板执行过程中执行不可逆命令如git push --force、rm -rf禁止在执行完测试后改动测试结果文件来“证明测试通过”写红线的意义在于给AI的每一次自由发挥加上刹车片。实测中这些红线条款确实把“AI乱改依赖、乱删文件”这类事故的发生率降到了零。5. 模板不是一次性的维护与团队复用5.1 模板腐化三个月不更新不如不写模板最容易被忽略的问题是“过期”。我有个很惨痛的教训一个错误码规范模板项目组三个月前已经把错误码从四位改成了六位但我没更新模板导致AI按旧规范生成了一堆错误码后面返工改了两天。从那以后我建立了模板的健康检查机制每两周做一次检查所有命令模板里提到的命令是否仍然有效比如mvn test是否被./gradlew test替代检查CLAUDE.md里的版本号、目录结构是否和当前项目一致检查模板里引用的文件路径是否还存在检查那个“高频命令”段落里的构建命令是否还能跑通这个机制主要靠代码维护我会顺手把模板库纳入版本控制。这样模板的每一次变更都有历史记录谁改的、为什么改都能追溯。用Git管模板是我觉得最值的一个决定。5.2 团队共享一人写好全组受益模板如果只停留在自己终端里价值最多发挥三成。当我把它做成一个独立仓库claude-code-templates团队成员git clone就能用到同一套规范时全组的AI使用质量都被拉齐了。团队共享有两个细节要注意。第一不要把个人偏好写进共享模板。我自己的模板里有一些个人习惯比如用JUnit 5的Nested组织测试团队其他人未必认同。后来我把这些分成人个本地模板和团队共享模板两套共享模板只放团队一致认可的规范。第二共享模板要配一个说明文档。不要指望同事打开模板就知道怎么用。我会在仓库里放一个README.md写清楚目录结构、每个命令的用法、添加新模板的流程。有了入口文档团队采用率会高很多否则同事只会在遇到问题时才勉强看一眼。5.3 我的演化节奏和最后一个小技巧说到演化节奏我现在基本遵循一个原则“高频任务优先、真实反馈驱动”。每季度末花一天时间把这三个月里AI回答得最好的三次任务记录找出来把它们回填进对应模板里。这个方法简单但极其有效——模板会随着你的使用质量同步进化。最后再分享一个小技巧Claude Code自己生成的优质回复别让它消失在对话历史里。当你发现某次任务中AI的输出超出预期地好直接把优质回复的关键结构提炼出来写进模板的输出示例区。模板里带上“正面示例”之后AI对格式和内容的理解会明显上一个台阶。这一点是我用下来觉得性价比最高的改进方式比反复强调“请按规范写”要有用得多。
上个季度给一个微服务项目补单元测试我对着同一个终端里的Claude Code连续问了三次“给这个模块写测试”三次回答风格完全不一样第一次用了JUnit 5的ParameterizedTest第二次用的是Mockito原生写法第三次把断言库换成了AssertJ。模块还是那个模块需求还是那个需求但AI的输出像三个不同的人写的。排查了半天才发现问题不在模型而在我——我从来没有告诉过它这个项目的测试规范、依赖版本、代码风格和红线约束每次都在靠临场发挥。后面我开始着手整理一套自己的claude-code-templates把高频任务的项目背景、输出规范、避坑约束全部固化下来。效果立竿见影同一个任务的回复风格基本稳定了我在代码审查上花的时间少了三分之一。这篇文章就是这段时间的完整复盘里面包含了我的目录结构、模板写法、踩过的坑以及团队复用时的版本管理思路适合重度使用Claude Code、正在被“输出不稳定”困扰的开发者参考。1. 为什么我最终转向了claude-code-templates这种“预制菜”模式1.1 直接对话的三个坏味道遗忘、漂移、重复劳动先说最直观的问题上下文遗忘。Claude Code的对话窗口有上下文上限哪怕没到上限聊到后面它也会“选择性失明”。我经常遇到的情况是聊到第三十个来回的时候它已经忘了项目用的是Spring Boot 3.2而不是2.7忘了数据库迁移脚本必须放在db/migration目录下甚至忘了我开局说的“不要动公共模块”。这不是模型的智力问题而是信息管理问题。你想想人开会也要先宣读会议纪要和项目背景不可能每个新同事来都从零开场。AI也一样它需要一份“入职文档”。然后是风格漂移。同一个任务今天早上问和下午问结果能差出两个档次——早上它规规矩矩按你上次的反馈改下午它又开始“自由发挥”。我最后总结出一个规律只要对话是靠临场措辞描述的输出质量就必然依赖你当时描述得有多细致、多巧。这不是玄学是概率。你把条件写清楚了它的采样空间就小了结果自然更稳定。最后是重复劳动。每个新任务都要重新交代技术栈、目录约定、提交规范、禁用词列表。写一个模板之前我每开一个任务都要先粘贴一大段背景说明少则两三百字多则上千字。这些字打完心态已经累了一半。1.2 模板的真正价值把隐性约束变成显性输入那有人会问直接写一个巨型提示词不就行了不行。提示词是一次性的写在对话里它会被后续内容淹没换个会话就没了。而 claude-code-templates 的价值在于把提示词变成了仓库里的持久资产。具体来说它做了三件事固定变量技术栈版本、目录结构、命名规范、错误处理偏好这些东西写成模板之后每个会话开局就注入不需要重复输入。固化约束哪些代码不许写、哪些目录不许动、哪些库不许引入直接写死在模板里AI跑偏的时候能拉回来。沉淀最佳实践你上一次发现“这个项目的异常处理应该用业务异常而非通用Exception”写进模板后下一次它就会默认遵守。换句话说模板是给Claude Code的“企业文化手册”。AI本身不懒它只是不知道你的规矩。你把规矩写清楚它就能照着办事。这个转变让我从“每次对话都要当项目经理”变成了“写一次模板、长期受益”。2. 一套可落地的模板仓库应该长什么样2.1 CLAUDE.md挂在项目门口的“永久记忆”Claude Code原生支持项目级的CLAUDE.md文件放在项目根目录每次会话启动时它会自动读取这个文件作为背景上下文。这是整个模板库的地基我所有的项目模板都会从这里开始。我自己的CLAUDE.md结构固定在五个段落后来发现这个结构对大部分技术项目都适用项目概览与技术栈两三句话说清楚这是什么项目、用什么语言、关键依赖版本。目录结构与职责边界哪个目录放什么、哪个模块是核心、哪些改动必须先通知相关负责人。代码规范与命名约定包名怎么起、接口怎么命名、提交信息格式。禁用与红线不许引入什么依赖、不许直接改哪张表、不许可用哪些被废弃的API。高频命令构建命令、测试命令、lint命令、单测单跑的快捷方式。举个例子一段我实际用过的CLAUDE.md片段# 项目记忆每次会话自动加载 ## 项目概览 - 结算服务settlement-serviceJava 17 Spring Boot 3.2.x - 主要负责账单生成、对账、差错处理依赖 payment-client 与 accounting-core ## 目录约定 - 业务逻辑放在 domain/ 下不要写进 controller/ - 数据库迁移脚本放 db/migration/按日期命名V20240101__xxx.sql - 外部接口适配放 adapter/ 下禁止在 service 里直接调第三方 SDK ## 代码规范 - Controller 只做参数校验和响应包装一律走 Service 层 - 异常统一抛 BizException(code, msg)禁止裸抛 RuntimeException - 提交信息格式feat|fix|refactor|test: 简短描述 ## 禁用与红线 - 禁止新增对 legacy-db 的直接 JDBC 访问统一走 settlement-mapper - 禁止在事务内调用远程 RPC容易长事务 ## 高频命令 - 全量单测mvn test - 单测单个类mvn test -DtestOrderCalculateTest这个文件写完之后最大的变化是新会话不再需要我重复说明“项目是干嘛的”它自己就知道。CLAUDE.md就是给Claude Code的入职手册值得花半小时认真打磨。2.2 斜杠命令高频任务从十句话变为一条命令CLAUDE.md解决的是“全局背景”但具体到某个高频任务比如“写接口文档”“补单测”“代码审查”你还需要一套更聚焦的任务模板。在Claude Code里这对应slash command我放在.claude/commands/目录下每个文件是一个Markdown命令。我维护过的最实用的几个斜杠命令/review让AI按项目的代码规范审查改动输出问题清单和修复建议。/test为指定的类生成单元测试要求模拟边界条件和异常分支。/doc给指定的接口或模块生成文档按团队模板输出。/refactor在不动公共接口的前提下优化代码结构必须列出改动影响面。每个命令文件的结构也很简单头部放YAML frontmatter写命令元信息正文是具体指令。例如/test命令--- description: 为指定类或模块生成单元测试 argument-hint: 类名或模块路径 --- 请为 $ARGUMENTS 生成单元测试遵守以下要求 1. 测试类放在 src/test/java 下包名与被测类保持一致 2. 优先使用 Mockito AssertJ禁止引入新的测试框架 3. 必须覆盖 - 正常路径happy path - 参数为空/越界的边界情况 - 业务异常分支BizException 的 code 和 message 4. 测试方法命名方法名_场景_预期结果如 shouldCalculateSuccess_WhenValidOrder_ReturnAmount 5. 最后检查一遍测试必须能独立运行不依赖本地环境变量或外部服务这套东西的价值在于把每次都要口述的长指令压缩成了两条斜杠。我实测过写交互式提示词的时候同样的要求我能打出两百字但写成/test 订单服务之后AI执行的就是一个结构完整的任务质量稳定很多。2.3 子代理模板把“无所不能”拆成“各司其职”Claude Code还有一个我很喜欢用的机制子代理subagents。它的作用是让AI以专属角色并行处理子任务每个角色有独立的系统提示和工具权限。我把它也纳入模板体系放在.claude/agents/目录下。我项目里长期维护过的子代理角色有三个code-reviewer只读代码分析潜在Bug、安全隐患、性能问题输出裁剪后的建议清单。test-writer只能写测试代码不能动业务代码。它的权限是有限的这反倒能避免AI顺手改业务逻辑。doc-writer专门把代码改动整理成可读性强的文档输出给非技术同事看。每个子代理文件就是一个带YAML frontmatter的Markdown文档写明角色名称、职责描述、允许调用的工具。例如--- name: test-writer description: 专注于生成高质量单元测试绝不修改被测业务代码 tools: Read, Grep, Test, Write --- 你是一名测试工程师任务是为指定模块编写单元测试。你只允许新增或修改测试文件禁止修改 src/main 下任何业务代码。如果发现业务代码存在问题把它记录在最终报告的“发现的业务问题”一栏等待人工处理。子代理最大的好处是角色隔离。以前我一个人让它“先写代码再补测试再审查”它经常在写测试时顺手改了业务代码。拆成多个角色模板之后每个角色只看自己的工作边界越权的情况少了很多。3. 从零搭建模板库先钉死高频重复场景3.1 第一步复盘你一周内反复做过的事情很多人一上来就闷头写模板结果写了几十个能用上的没几个。我的建议是先复盘再动手。打开你的终端历史和IDE使用记录翻出过去一周的对话记录统计一下哪些事情你反复在做。我当时的统计结果大致是这个分布任务类型一周出现次数单次耗时写/补单元测试14次15-30分钟接口文档生成9次10-20分钟代码审查自己改完让别人看8次10-25分钟重构旧代码6次30-60分钟排查线上日志/异常5次20-40分钟这个列表就是模板库的索引。排序靠前的任务优先做模板靠后的可以先不碰。用真实频率决定优先级比拍脑袋规划靠谱得多——至少我后来不会再因为“我可能用得上”写一些僵尸模板。3.2 第二步写第一个模板时死磕的五个要点模板和提示词不一样它要承载“长期使用”的重量。我写第一个模板反复改了七八版最后总结出五个要点缺一不可。要点一给出负面清单Dont比追求正面指令更重要。你告诉AI“要做什么”它总能理解几分但你要是不告诉它“不许做什么”它大概率会在某个边界上踩线。比如写测试模板我特意加了“禁止引入新的测试框架”“禁止修改被测类”这两条防住了大部分失控操作。要点二输出格式一定要显式约束。人和AI协作最大的成本其实是“读它的输出然后改”。如果模板里不指定输出格式AI会自由发挥成一大段叙述文字指定格式之后比如“问题清单用表格、每条必须包含优先级和修复建议”它的输出就变得可以直接粘贴进工作流。这件事在第四个章节里我会展开讲。要点三预设变量而不是写死内容。模板要能复用必须留参数位。我的斜杠命令都用了$ARGUMENTSCLAUDE.md里则用路径占位符比如module-name。宁可模板里多几个占位符也不要写得太具体导致换个项目就要改一半。要点四给AI留出“提问/确认”的通道。模板不是把人锁死而是给AI一个“拿不准时怎么办”的出口。我常用的做法是在模板末尾加一段“如果以上要求有任何与项目实际情况冲突的地方请指出冲突点并暂停执行等待用户确认。”这避免了AI不问就乱干的尴尬。要点五写完后用三个真实场景试跑一遍。模板看着顺眼不算数拉一个真实任务跑一遍才算数。我自己有个固定流程写完模板后连跑三个任务只观察一件事——AI的输出质量是不是优于我临场写提示词的结果。如果不是就改模板再试。3.3 第三步用真实项目迭代而不是凭空设计我必须强调模板是迭代出来的不是设计出来的。我最开始为“接口文档”写了一个自认为很完整的模板实际用了两次就发现两个问题一是它要求的输出结构太细AI为了填结构反而忽略了内容的准确性二是它没考虑到“接口文档需要同时输出给前端和后端两拨人”这事导致模板里的术语两边都不满意。后来我把文档模板砍掉了三分之一的内容改成两段式输出一段给前端请求参数、返回示例、错误码一段给后端实现细节、边界条件、依赖关系。跑了几周才稳定下来。我更推荐的做法是把模板当成代码对待每次使用后顺手记一笔“这次哪里不对劲”攒够问题就改一版。这在工程上叫“小步迭代”用在模板上完全成立。一套成熟模板从来不是一次写成的而是十几次使用后打磨出来的。4. 模板真正好用起来靠的是这几个细节4.1 输出格式约束比内容描述更重要这是我从大量试错里得到的最反直觉的一条经验。刚开始我写模板精力全放在“描述任务内容”上比如“请重构这个模块并保持功能不变”结果AI输出了一大段“这是一个很重要的模块经过分析我建议……”的废话——它把重构过程写成了汇报材料我没法直接用它。后来我改了模板把重点放在输出格式上。同样的重构任务我要求它按三段式输出第一段“改动摘要”最多三行第二段“改动文件清单”含每个文件的改动描述第三段“风险点”列出可能影响的范围。改完之后AI的输出立刻变得“能干活”了。给一个我实际用的输出格式模板片段## 输出要求 请严格按照以下结构输出不要添加开头结尾套话 1. 原问题定位一句话说明当前代码存在的问题 2. 修改方案表格文件 | 改动点 | 影响范围 3. 验证方式你打算怎么测试这次改动命令是什么这个细节的核心逻辑是AI很擅长填空但不擅长猜你想要什么格式的答案。你把格式作为模板的最高优先级它就会把精力留给真正的问题。4.2 变量注入不要在每个模板里硬编码模板库建到中期我遇到一个尴尬的情况一共有十几个模板文件每个文件里都写了同样的三行项目背景技术栈、目录约定、红线段落。结果项目升级了一次Spring Boot版本我要改的地方是十五个文件而不是一个。这就是硬编码的代价。我的解决方案是层级化拆分配置。CLAUDE.md里放全局信息斜杠命令里只引用任务本身的要求不重复背景。如果某个任务必须知道技术栈我让命令里用$ARGUMENTS接收参数或者直接写“技术栈信息见CLAUDE.md”。这样做的另一个好处是如果你同时维护多个项目比如一个Java微服务和一个Python脚本仓库你的斜杠命令模板可以共用只有CLAUDE.md不同。我的.claude/commands/目录已经做到了跨项目复用这全靠变量和引用而不是复制粘贴。4.3 与MCP工具链联动时的三个注意事项Claude Code支持MCPModel Context Protocol可以用它把内部API、数据库、监控平台等接进对话。模板和MCP联动时我踩过几个坑值得单独说一下。第一个坑模板里设计的步骤假设了工具可用但实际没接。写模板时觉得“反正可以调测试平台”结果在不通MCP的环境下这个模板直接半路卡住。后来我每个模板开头都加一条“如果下列工具不可用请跳过相关步骤并明确告知”模板立刻变得健壮。第二个坑工具权限过大。MCP可以集成数据库查询、文件写入、甚至线上配置发布这给模板带来了风险。我在模板里明确约束了工具的调用边界比如“只允许调用只读查询接口禁止调用变更类接口”。这条约束不能只靠AI自觉最好配合工具侧的权限配置双保险。第三个坑MCP返回的数据格式不稳定。有时候MCP返回JSON有时候返回Markdown表格模板里的后处理逻辑就会失效。我的做法是在模板里要求“所有MCP返回的数据先整理成统一格式表格再做下一步分析”。多花几秒钟整理能省掉大量后续纠错。4.4 危险操作兜底模板里必须有红线模板是为了让AI做得更好但也意味着你会把更多权限交给它。这时候模板里必须写清楚“什么不能做”。我把这个叫红线条款每一个涉及文件修改或命令执行的模板里都有。我在CLAUDE.md和命令模板里固定保留了这几条禁止直接删除代码文件除非用户明确同意禁止修改依赖版本号升级依赖必须人工做禁止在模板执行过程中执行不可逆命令如git push --force、rm -rf禁止在执行完测试后改动测试结果文件来“证明测试通过”写红线的意义在于给AI的每一次自由发挥加上刹车片。实测中这些红线条款确实把“AI乱改依赖、乱删文件”这类事故的发生率降到了零。5. 模板不是一次性的维护与团队复用5.1 模板腐化三个月不更新不如不写模板最容易被忽略的问题是“过期”。我有个很惨痛的教训一个错误码规范模板项目组三个月前已经把错误码从四位改成了六位但我没更新模板导致AI按旧规范生成了一堆错误码后面返工改了两天。从那以后我建立了模板的健康检查机制每两周做一次检查所有命令模板里提到的命令是否仍然有效比如mvn test是否被./gradlew test替代检查CLAUDE.md里的版本号、目录结构是否和当前项目一致检查模板里引用的文件路径是否还存在检查那个“高频命令”段落里的构建命令是否还能跑通这个机制主要靠代码维护我会顺手把模板库纳入版本控制。这样模板的每一次变更都有历史记录谁改的、为什么改都能追溯。用Git管模板是我觉得最值的一个决定。5.2 团队共享一人写好全组受益模板如果只停留在自己终端里价值最多发挥三成。当我把它做成一个独立仓库claude-code-templates团队成员git clone就能用到同一套规范时全组的AI使用质量都被拉齐了。团队共享有两个细节要注意。第一不要把个人偏好写进共享模板。我自己的模板里有一些个人习惯比如用JUnit 5的Nested组织测试团队其他人未必认同。后来我把这些分成人个本地模板和团队共享模板两套共享模板只放团队一致认可的规范。第二共享模板要配一个说明文档。不要指望同事打开模板就知道怎么用。我会在仓库里放一个README.md写清楚目录结构、每个命令的用法、添加新模板的流程。有了入口文档团队采用率会高很多否则同事只会在遇到问题时才勉强看一眼。5.3 我的演化节奏和最后一个小技巧说到演化节奏我现在基本遵循一个原则“高频任务优先、真实反馈驱动”。每季度末花一天时间把这三个月里AI回答得最好的三次任务记录找出来把它们回填进对应模板里。这个方法简单但极其有效——模板会随着你的使用质量同步进化。最后再分享一个小技巧Claude Code自己生成的优质回复别让它消失在对话历史里。当你发现某次任务中AI的输出超出预期地好直接把优质回复的关键结构提炼出来写进模板的输出示例区。模板里带上“正面示例”之后AI对格式和内容的理解会明显上一个台阶。这一点是我用下来觉得性价比最高的改进方式比反复强调“请按规范写”要有用得多。
