用 Claude Code 写代码这件事我前后折腾了两个多月。最开始就是把它当成一个附赠上下文能力的终端助手打开项目目录把问题往对话框里一贴让它生成函数、补测试、修修 bug。后来慢慢发现同样一个工具裸用和带着模板用产出的质量差距相当大。这也就是 claude-code-templates 这个项目的由来——我把日常开发里反复要用到的 Claude Code 指令沉淀成一套可复用的模板文件让它换到哪个仓库、哪个语言都能输出稳定水准的代码结果。这篇文章我会把模板的设计思路、目录结构、几个可以直接抄走的模板示例以及我在真实项目中踩过的坑完整过一遍。想认真用 Claude Code 而不是随手玩玩的开发者应该都能从中拿到一些能落地的经验。1. 为什么需要给 Claude Code 准备模板1.1 裸用 Claude Code 时最疼的几个点先说裸用。这里说的裸用指的是不建模板、不固化任何自定义指令每次打开终端就在默认对话里直接输入需求。这种方式胜在灵活但用得久了会遇到几个非常现实的问题。第一个问题是上下文重置。Claude Code 虽然能识别当前目录但它并不天然知道你项目的技术栈、目录约定、测试框架、命名风格每次都得重新告诉它这是一个 TypeScript 的 monorepo前端是 React后端是 Fastify测试用 Vitest别碰 generator 目录下的代码。刚开始你还有耐心打时间一长要么啰嗦要么漏了关键信息模型就只能靠猜猜错就是返工。我印象很深的一次忘了告诉它项目里用了 pnpm 而不是 npm它给我生成的 CI 步骤全是 npm 命令整个流水线直接红了大半天。第二个问题是输出格式不稳定。同样让它做代码审查今天它给你一段流畅的总结明天分条列出问题后天直接改好了代码只附一句已修复。如果你需要的是规范化的审查清单这种随机性会很折磨人。模型非常擅长模仿格式但它默认会自己选一个最顺手的格式而这个顺手不一定是你要的。我在团队里拉过一次测试三个人用同一个仓库同一个问题去问得到的三份答案结构完全不一样开会复盘时根本没法对照。第三个问题是能力漂移。没有约束的时候Claude Code 会表现得过于激进。我说把这个模块重构一下它能顺手把不相关的文件也格式化一遍或者自作主张把测试里的断言改掉。这种能力对老手来说还能接受但对需要谨慎的代码库就是安全隐患。我在一个支付项目里它一次重构顺手给我把日志脱敏逻辑删了一半原因只是它觉得那段代码冗余。没有模板里的护栏这类事情防不胜防。最后还有一个容易被忽略的点不可复用。你在 A 项目里好不容易用一大段话调教出一个最佳实践到了 B 项目里一切从零开始。这种隐性成本久了会让大家觉得AI 助手只是个玩具。其实不是玩具是没把它变成资产。1.2 模板到底解决了什么问题模板就是把这些每次都重复的开场白和行为准则固化下来让 Claude Code 每次开工前先读一遍自己的纪律。我自己的理解是Claude Code 本身就像一个能力很强但记性不好的外包工程师。每次新开一个项目他完全不记得上次你是怎么跟他配合的。模板就相当于一份员工手册把该做什么、不该做什么、按规定交付什么写得清清楚楚这样哪怕换了个新工程师交接成本也能控制住。你不需要每次都手把手教他你是个什么人、项目什么情况、完成标准是什么手册替他记住了。所以模板至少解决四个问题。一是稳定输出格式、深度、语气在模板里约定好结果可控二是知识沉淀团队里最好的用法可以沉淀成文件而不是留在某个离职同事的终端里三是一致协作所有人用同一套模板审查的标准、生成代码的风格、补测试的粒度都能对齐四是低成本复用换仓库、换项目模板一拷过去就能用不用每次重新措辞。这几条我每个都切身体会过尤其是团队协作那一项有了统一模板之后大家互相 review 的代码风格明显一致了不少。2. 模板的核心结构与设计要点2.1 一段模板的骨架角色、背景、约束、交付物我后来把自己所有模板整理了一遍发现它们骨子里都是同一个结构四个部分角色、背景、约束、交付物。不管你是让 Claude Code 写测试、做审查、重构代码还是生成 commit message这四个部分都能套。角色是最容易被忽略的。同样是帮忙审查代码你是一名严格的代码审查员和你是一名有十年后端经验的资深工程师正在做上线前的最后审查产出的严格程度完全不一样。角色定义了模型模仿的对象和语气相当于给它一个行为锚点。我自己试过把审查模板里的角色从专业代码审查员改成安全敏感的支付系统优化专家之后它发现数据校验问题的敏感度明显上了一个台阶。背景是让模型不至于瞎猜的信息。项目类型、主要语言、测试命令、重点关注的目录、是否有 CI这些都应该给到。不需要每次写模板时都填全模板里可以留变量运行时再注入。背景信息不一定要写进模板文件本身可以让模板里注明先阅读 README 和 package.json让模型自己去拿效果反而更好。Claude Code 本身具备文件读取能力这个机制我后面会细说。约束是最关键的护栏。明确写清楚只读不要修改任何文件不要执行破坏性命令不要改动测试断言不要重排 import 顺序不要删注释等等。约束写得越具体模型越不会发挥。我以前总觉得约束写太多会限制模型的能力后来才发现绝大部分偏离预期的问题都不是能力不够而是没有规则。规则就是模型的安全带。交付物则规定了最终产物长什么样。要一份 Markdown 报告还是要一个 diff 文件还是直接改代码并运行测试如果交付物不明确模型会自己选一种方式这也是输出不稳定的根源。我在模板里几乎都会指定交付物格式比如输出一份 Markdown 审查报告包含问题清单、风险等级、修改建议。2.2 动态变量与上下文注入模板如果写死复用价值就大打折扣。所以我会在模板里用占位符实际使用的时候再填充。比如{{项目类型}}、{{测试命令}}、{{目标文件}}。用的时候有两种常见方式一种是把模板内容复制出来手动替换占位符再粘贴到 Claude Code 里另一种是用 shell 拼 prompt直接通过 Claude Code 的命令行参数把模板内容和任务描述一起喂进去。我一直用的是后一种把模板当作 prompt 的骨架动态拼进目标文件路径和具体任务。举个例子执行claude -p $(cat templates/review.md) -- 目标是 src/payment/service.ts测试命令是 npm test模板内容就自动变成了这次任务的完整指令。这样模板本身不用存储任何具体仓库信息保持通用具体任务交给命令行参数去填充。一个更聪明的做法是让模板告诉 Claude Code 自己先去读项目里的关键文件。例如模板里写开始之前请先阅读 README.md、package.json、tsconfig.json了解项目结构和依赖再开始工作。这样就不用把背景全部塞进模板模型读完文件之后能自己整理上下文。实测下来让模型自己读书面材料比你在模板里用几百字描述项目背景要准确得多因为文件里的信息不会因为你的转述而失真。下面是几种常见模板的定位对比我按自己的使用频率排了个序模板类型核心目标最关键的一条约束典型交付物代码审查发现潜在 bug、安全问题、可维护性隐患只读禁止直接修改代码Markdown 审查报告测试补全补齐缺失的单元测试和边界用例不要为了覆盖率造无意义断言测试代码文件重构辅助在保持行为不变的前提下优化结构禁止同时调整无关代码变更后的代码和变更说明Commit 信息生成符合约定的提交信息严格按 Conventional Commits 格式一段 commit message文档生成从代码生成 API 文档/注释不要编造不存在的参数Markdown 文档文件这张表的核心意思是一句话每类模板的目标越单一约束越明确效果越稳。我见过有人想写一个万能模板什么都能干结果是什么都干不好。3. 从零搭建一套能直接复用的 Claude Code 模板3.1 目录结构与命名规范我先说目录结构。我的模板仓库长这样claude-code-templates/ ├── README.md ├── review.md ├── test.md ├── refactor.md ├── commit.md └── docs.md命名用动词开头让人一眼看出是干什么的。避免template1.md、111.txt这种名字三个月后你自己都认不出来。每个模板的文件名就是它的使用场景review 是代码审查test 是测试补全refactor 是重构commit 是生成提交信息docs 是生成文档。如果模板多了再按二级目录分类比如review/safety.md、review/performance.md。每个模板文件头部我会放一小段注释写清楚这个模板的适用场景和必须提供的变量。这个习惯特别重要因为模板迟早会被团队其他人拿去用没有注释的话对方根本不知道这个模板需要填什么。# review.md # 用途对指定文件做代码审查重点关注安全和边界条件 # 输入变量目标文件路径测试命令3.2 能直接抄的代码审查模板下面这份是我目前每天都在用的代码审查模板直接抄走就能用。你是一名有十年后端开发经验的资深工程师擅长 Web 服务、支付系统和高并发场景。 现在需要对指定文件做一次上线前的代码审查。 背景信息 - 目标文件{{FILE_PATH}} - 项目测试命令{{TEST_COMMAND}} - 请先阅读 README.md 和 package.json了解项目背景后再开始 审查时必须关注 1. 安全问题注入风险、敏感信息泄漏、越权访问、数据校验缺失 2. 边界条件空值、溢出、超时、并发、重复请求 3. 异常处理错误是否被捕获是否暴露了内部信息 4. 可维护性命名、函数复杂度、重复代码、过深嵌套 5. 性能隐患大循环、不必要 IO、内存泄漏 约束 - 只允许阅读代码禁止修改任何文件 - 禁止执行破坏性命令禁止运行副作用较大的测试 - 不要重新格式化代码不要提与目标文件无关的问题 交付物 输出一份 Markdown 审查报告结构如下 - 总体评价100 字以内 - 问题清单风险等级高/中/低、文件位置、问题描述、修改建议 - 值得肯定的设计如果存在使用方式是把模板内容存成文件命令行里拼上具体参数claude -p $(cat templates/review.md) -- 目标文件是 src/payment/service.ts测试命令是 npm test这份模板里有几个关键设计。第一角色定义成资深工程师而不是审查员产出的建议更容易落地而非泛泛而谈第二给了明确的风险等级分类方便我们按优先级处理问题第三禁止修改文件因为审查和修改是两件事混在一起很容易让模型边审边改结果报告没写好代码还动了。3.3 测试补全模板示例第二个能直接用的模板是测试补全。代码审查是只读任务测试补全则是写代码任务所以约束部分完全不同。你是一名熟悉 Vitest/Jest 的测试工程师。现在的任务是为指定代码文件补齐单元测试。 背景信息 - 目标文件{{FILE_PATH}} - 测试命令{{TEST_COMMAND}} - 请先阅读现有测试文件和目标文件保持测试风格一致 编写测试时的要求 1. 覆盖核心业务逻辑的正常路径 2. 重点补充边界条件空输入、非法参数、超限值、异常抛出 3. 关注副作用外部调用是否被 mock数据库连接是否正确隔离 4. 每个测试用例必须有清晰的描述说明在验证什么行为 约束 - 只修改测试文件禁止改动被测源码 - 不要为了覆盖率硬编无意义断言 - 不要删除现有测试用例 - 断言必须真实有效禁止写永远为真的空断言 交付物 直接输出新增测试代码并说明每个用例对应的业务场景。实际使用效果比我预期的好很多。原因是模板里强制它先读现有测试文件这让它模仿现有测试风格而不是自创一套风格。补出来的测试放在项目里第一感官就和原有测试非常协调review 的人也不会觉得突兀。使用方式和审查模板一样把具体文件路径和测试命令拼进去。我一般会追加一句请先运行现有测试确认通过后再补充这样它更清楚当前基线状态。3.4 把模板挂到 CLAUDE.md 和斜杠指令里每次敲一大串命令虽然比裸用好但还是有点烦。所以我更喜欢的方式是把最常用的模板做成 Claude Code 的自定义斜杠指令这样在交互式对话里输入/review就能直接触发模板。做法是建一个/project_dir/.claude/commands/目录把模板文件放进去。以代码审查为例我建.claude/commands/review.md内容基本就是上面的审查模板只是把变量部分改成用户会在对话中提供目标文件路径和测试命令。配置好之后在 Claude Code 输入框中直接敲/review它就会加载这个模板然后再追加上你要审查的文件路径。不需要再记忆模板内容也不用拼命令行参数完全回到对话式交互非常自然。CLAUDE.md 是另一个关键文件。它相当于项目级的长期记忆Claude Code 每次启动都会自动读取。我会把项目层面的稳定信息放在这里比如技术栈、代码风格、常用命令而不是把大段任务模板塞进去。CLAUDE.md 管的是这个项目长期是什么样模板管的是这次任务具体要做什么两者分工明确。常规的 REPL 流程里这两者配合好之后Claude Code 的行为会非常稳定。4. 踩坑记录模板不是写完就能用4.1 模板越长模型越容易摆烂我最早写过一份八百字的超级模板试图把代码审查、测试、重构、安全规范全部塞进去。结果很惨Claude Code 经常只执行后半部分或者挑它最熟悉的部分执行开头一大半角色和背景说明直接被忽略。长指令会导致注意力被稀释模型会优先处理它最适应的任务类型而不是完全按照你的顺序来。复盘之后我把模板压缩到三百字以内原则是核心指令必须出现在显眼位置长篇论述拆到单独文档里让模板用一句话引导模型自行去读细节。比如背景见 CLAUDE.md和详细规范见 docs/security-checklist.md模型需要详细内容时会主动去读。压缩后的模板执行力明显回升输出质量和稳定性都有肉眼可见的提升。4.2 输出格式忽好忽坏怎么解决格式不稳定的问题大部分都出在交付物描述不够具体。之前我在测试补全模板里只写了输出测试代码模型有时直接修改文件有时只给建议有时输出测试代码的同时还把源码也改了。后来我改成明确指定直接输出新增测试代码不要修改源码并规定好代码组织顺序问题基本消失。另一个技巧是给模型看一个格式样本。比如在审查模板开头放一句参考格式问题清单必须包含风险等级、文件位置、描述和建议。有时候哪怕你写了很多说明它还是不知道你想要什么样式给一个具体示例比抽象描述有效得多。我现在在 commit 信息模板里就直接附上两个优秀示例生成结果几乎没有再来回的。4.3 权限和安全边界怎么捏死Claude Code 具备执行终端命令的能力这既是优势也是风险。模板里如果没有安全约束它可能在你只想审查代码的时候顺手跑一个格式化命令或者安装依赖。我踩过一次坑让模型优化测试性能它直接改了 CI 脚本里的一段 shell 命令差点把发布流程搞坏。所以我在所有模板的约束区都写死了几条铁律禁止执行破坏性命令禁止修改 CI 配置禁止删除历史记录禁止自动 push禁止改动锁文件。如果任务确实需要这些操作我会在对话里单独授权而不是让它自行决定。另外Claude Code 自己的权限配置也要配合收紧不要让 AI 助手拿到比日常工作所需更大的权限。安全边界这件事宁严勿松。4.4 模板在团队里的版本管理模板一旦在团队里用起来就不再是个人小工具会变成团队资产。这个时候版本管理必须跟上。我的实践是模板跟随仓库一起放进 Git每一个模板文件的改动都走普通的 PR 流程让改动可追溯。命名上不要用review_final.md、review_newest.md这种东西直接叫review.md迭代靠语义化版本和历史记录来体现。遇到最典型的问题就是有人改了模板之后其他人还在用旧版本结果两个人给出来的输出标准不一致。所以我会在 README 里写清每个模板的版本号和最近变更内容谁改了模板要在 PR 描述里说明影响范围。模板本身也被纳入代码审查流程因为它直接影响 AI 助手的行为反过来说它就是团队工程质量的一部分。最后再说一点个人体会。模板不是一次写好的我的 review 模板到现在已经改了十几版每次遇到一个好用的用法就往里加一句每次遇到模型跑偏就往约束区加一条。关键是先跑起来再迭代。这套 claude-code-templates 我现在每天打开终端都在用你也可以先抄几个回去试试用不舒服的地方按自己的习惯改改着改着它就变成你的了。