1. 项目概述claude-code-templates 到底解决什么问题1.1 一个真实场景没有模板时Claude Code 有多“被动”我先说个自己的经历。项目刚用 Claude Code 那会儿我最常干的一件事是把它当高级搜索引擎claude 帮我 review 一下 src/ 下面的代码输出一般长这样“整体结构清晰代码可读性良好建议优化异常处理逻辑。”听起来挺对但没有任何用。你说“详细一点”它才多写两段你说“按文件过一遍”它才开始逐文件挑问题。你推一步它动一步永远不主动交付你能直接拿去用的东西。这其实不怪模型问题出在提问方式上。同样一个代码审查任务老手会在一开始就把约束说清楚扮演什么角色、看哪些文件、关注哪几类问题、最后按什么格式输出。这些“人话需求”一旦变成模板效果立刻不一样。claude-code-templates 这个项目做的就是这件事把高频任务里那些“每次都重复的提示词”沉淀成可复用的 Markdown 模板再配合 Claude Code 的命令行能力让 AI 从“被动聊天的助手”变成“按团队规矩干活的结对开发者”。适合所有正在用或者准备用 Claude Code 做代码审查、测试生成、重构、提交信息规范化的个人开发者和团队。1.2 模板到底“模”的是什么有人觉得模板不就是一段长提示词吗是也不是。一段好的模板至少会做三件事。第一固定角色。是“资深后端工程师”“单元测试专家”还是“技术文档写手”AI 的输出语气、关注点、专业深度完全不同。角色定不对代码审查会用测试视角去挑错文档生成会用架构师口吻去教育人。第二固定任务边界。审查就审查业务逻辑、并发安全、异常处理这几类不要顺带把整个项目重写一遍。边界不清AI 容易自由发挥输出一大篇“改进建议”看着热闹落地为零。第三固定输出格式。问题要按严重级别分类每条带文件位置、原因说明、修改建议测试要用 pytest 组织mock 哪些依赖、覆盖哪些边界都要写清楚。AI 是很擅长模仿格式的你把格式框死它就能交出一份可以直接建工单、直接合入 MR 的结果。这个项目里的每个模板本质上都是在把这三件事做成“骨架”往骨架里填变量就能在不同仓库、不同语言、不同任务里复用。模板不是限制 AI而是给 AI 一个稳定的“工作界面”。2. 模板库的整体设计与核心机制2.1 按任务场景拆模板的四个维度我整理 claude-code-templates 时不是随手攒几段话而是先定义了四个维度保证每个模板都有稳定的骨架。角色RoleAI 以什么身份工作。比如你是拥有十年经验的 Python 后端工程师负责 Code Review。任务Task具体做什么。比如“审查指定目录下所有 Python 文件重点检查并发安全、异常处理、资源释放”。约束Constraints绝对不能做什么。比如“不要修改任何代码文件”“不要输出与问题无关的赞美性总结”“一次只处理一个文件”。输出格式Output Format交付形态。比如“按 Markdown 表格输出列字段为文件、行号、严重级别、问题描述、修改建议”。这四个维度缺一个模板就会开始失控。角色解决“AI 怎么想”任务解决“AI 做什么”约束解决“AI 不做什么”输出格式解决“你怎么用它”。我见过很多失败模板要么没有约束AI 聊着聊着就开始改代码了要么没有格式输出的东西没法直接贴到 Jira 里。2.2 变量插值与模板加载方式模板不能写死。同样是代码审查Python 项目和 Go 项目的关注点完全不同同样是测试生成pytest 和 Jest 的写法也差很多。所以 claude-code-templates 里的模板普遍支持变量插值约定用双花括号{{source_file}} # 目标文件 {{language}} # 编程语言 {{test_framework}} # 测试框架 {{context}} # 额外背景加载时就地替换把渲染后的内容传给 Claude Codecat templates/test-generation.md \ | sed s/{{source_file}}/src\/utils.py/g \ | sed s/{{language}}/Python/g \ | claude -p有人会问为什么不直接在模板里写“请识别当前仓库的语言和框架然后生成测试”可以但代价是 AI 要多花上下文去识别识别错了后面全错。显式把变量填好AI 直接从正事开始干实测下来准确率高很多。2.3 为什么选 Markdown 而不是 YAML 或脚本拼接这个决定我纠结过。最开始想用 YAML 存参数、JSON 存变量后来全推翻了模板文件全部用纯 Markdown。理由很直接第一Markdown 是人机共读的。写模板的人能一眼看懂结构AI 读取时也不会被多余的结构层干扰。第二可以用 git 管理每次改动都能 diff团队 review 模板变更非常方便。第三编辑器天然高亮写起来舒服。YAML 和 JSON 的问题在于它们把“提示词文本”拆成了“字段结构”AI 读取时需要额外推理“这个 key 对应什么”反而增加了理解的不可控性。脚本拼接则把逻辑写死在程序里改一次模板要动一次脚本维护成本高。所以最终方案是提示词正文全放 Markdown变量用双花括号占位加载时用 sed 或模板引擎替换。这套组合简单、透明、可控任何一个用过命令行的人都能上手。2.4 模板的命名与目录规划目录规划也很重要。这个项目里我按任务类型分目录而不是按语言分templates/ ├── code-review.md ├── test-generation.md ├── refactoring.md ├── commit-message.md ├── architecture-design.md └── changelog.md好处是同一个 code-review 模板可以通过{{language}}适配不同技术栈不需要为每一种语言单独维护一套。模板首先是任务维度的抽象语言只是变量。模板文件适用场景关键输出code-review.md合并请求前的代码审查问题清单文件/行号/严重级别/建议test-generation.md为函数或模块生成单元测试可运行的测试代码文件refactoring.md在不改行为的前提下优化代码重构步骤与风险说明commit-message.md根据 git diff 生成提交信息符合 Conventional Commits 的单条提交信息architecture-design.md从需求到技术方案选型对比、模块划分、风险清单changelog.md根据 commit 生成变更日志按类型分组的 Markdown 日志3. 核心模板实操编写四个能直接抄作业的例子3.1 代码审查模板让 AI 按规矩挑毛病我用的代码审查模板长这样你是一位拥有十年经验的资深后端工程师正在参与一次严格的代码审查。 审查范围{{source_file}} 编程语言{{language}} 审查重点 1. 业务逻辑正确性 2. 异常处理是否覆盖了边界场景 3. 并发安全线程、协程、共享状态 4. 资源释放连接、文件句柄、内存 5. 可能的性能瓶颈 硬性约束 - 不要修改任何代码文件只输出审查意见 - 不要输出“整体质量很好”之类的笼统评价 - 每个问题必须定位到具体的函数名或行号 输出格式严格使用 Markdown 表格 | 严重级别 | 文件 | 行号 | 问题描述 | 修改建议 | 严重级别使用阻塞 / 重要 / 建议这个模板的核心是“审查重点 硬性约束 表格格式”三件套。审查重点决定了 AI 在哪个层面思考约束切断了它“边夸边改”的摸鱼路径表格格式让结果可以直接喂给下一个环节。实测效果没用模板时AI 输出一屏文字我要自己提炼谁去修用了模板后直接导成 Markdown 贴到 MR 描述里开发按行号就能处理。阻塞级别的问题AI 通常能命中 80% 以上剩下的人工过一遍。3.2 单元测试模板生成可运行的测试文件测试生成模板的坑在于AI 经常生成“看似合理但跑不过”的代码。所以这个模板里我最强调三点mock 策略、边界值和可运行性。你是一位熟悉 {{test_framework}} 的测试工程师。 请为 {{source_file}} 中的核心函数生成单元测试。 要求 1. 使用 {{test_framework}} 编写文件名为 test_xxx.py 2. 覆盖正常路径、空输入、极端值、异常输入 3. mock 掉所有外部 IO 依赖如网络请求、数据库连接、时间函数 4. 每个测试用例必须有清晰的 assert 断言 5. 不要修改被测源文件 输出格式 - 先输出完整的测试代码块 - 再用三行说明覆盖了哪些场景、哪些依赖被 mock、如何运行测试这里的“可运行性”是关键词。AI 生成测试时最大的问题是不清楚被测函数的外部依赖所以我在模板里强制要求它“mock 掉所有外部 IO 依赖”并在最后补充运行方式。加了这条之后测试代码从“看起来是测试”变成“能直接跑起来”的比例大大提高。3.3 Commit 信息模板跟 git diff 强绑定的提交信息Commit 信息模板是特殊的因为它不能凭空发挥必须绑定实际的代码变更。我通常这样调用git diff HEAD | claude -p $(cat templates/commit-message.md)模板内容你是一位熟悉 Conventional Commits 规范的工程师。 下面是一段 git diff 内容请根据它生成一条提交信息。 约束 - 提交信息必须使用 feat / fix / refactor / docs / test / chore 开头 - 主题行不超过 72 个字符 - 如果 diff 涉及多个变更只挑最核心的一个变更作为主题 - 禁止出现“update code”“fix bug”这类无信息量的描述 输出格式 第一行提交类型(影响范围): 主题 第二行空行 第三行开始变更原因和关键改动点的简要说明不超过 80 字为什么要用模板因为 AI 默认会写“feat: update code”这跟没写一样。把模板喂进去之后它会认真读 diff提取“新增了支付回调重试机制”这样的真实信息再按规范输出。配合脚本封装团队里所有人的提交信息格式能完全统一。3.4 架构设计模板把需求翻译成技术方案架构设计模板是输出最长的模板也是我项目里迭代次数最多的一个。我的团队经常要写技术方案文档ChatGPT 时代大家都写过“空话连篇”的方案所以模板里我最强调一件事每个选型必须说出理由和代价。你是一位系统架构师请基于以下需求给出初步技术方案。 需求描述 {{context}} 方案必须包含 1. 背景与目标一句话说清要解决什么 2. 约束条件性能、成本、团队熟悉度、部署环境 3. 候选方案至少给出两种可行方案 4. 选型理由对比表 最终选择 三个关键原因 5. 模块划分按职责拆成模块描述模块间依赖关系 6. 风险清单每个风险标注发生概率和影响程度 7. 阶段计划分三步落地每步有可交付物 硬性约束 - 不要使用“高性能”“高可用”“易扩展”这类空洞词汇 - 每个技术选型必须写明放弃的替代方案和原因行文到这里的逻辑是先让 AI 把“人话需求”吃进去再逼它输出有决策依据的方案。用这个模板产出的文档评审效率明显提高因为所有人都能直接在“选型对比”和“风险清单”上争论而不是纠结于方案里那些虚话。4. 在 Claude Code 里接入模板的完整流程4.1 第一步用命令行封装高频模板调用模板写好了接入方式决定你愿不愿意长期用。我的习惯是在 shell 里配置 alias把固定调用变成一条短命令# 代码审查 alias reviewclaude -p $(cat ~/templates/code-review.md) $ # 生成测试 alias gen-testclaude -p $(cat ~/templates/test-generation.md) $ # 生成提交信息 alias commit-msggit diff HEAD | claude -p $(cat ~/templates/commit-message.md)注意几个细节。-p是非交互模式适合脚本化调用不会进入对话循环后面的$可以把额外参数透传进去比如补充“只审查 auth 模块”这样的临时要求。模板路径建议用绝对路径避免在不同仓库间切换时找错文件。我第一次用的时候踩过一个坑没有加$导致每次调用模板后想追加一句“重点看并发问题”都没法传只能再开一个交互式会话去补充。加上$之后review 重点检查并发就能在模板基础上追加指令灵活很多。4.2 第二步把模板路径写进 CLAUDE.md 建立项目约定Claude Code 会自动读取项目根目录的CLAUDE.md把它当作用户自定义的项目规则。这是一个非常实用的接入点把模板的调用约定写进去AI 就知道什么场景下该用什么模板。我一般会在CLAUDE.md里加一段## 代码审查约定 当用户说审查代码或/review时遵循 templates/code-review.md 中的要求 - 加载该模板中的角色设定 - 审查范围默认是当前目录下所有源码 - 输出必须使用模板规定的 Markdown 表格格式 - 不允许修改任何代码文件这种做法比每次手动传模板更接近“团队规范”的体验。AI 在项目里一开始就带着这些规则不需要用户每次重复。CLAUDE.md 本身的通用配置可以单独维护模板文件集中在 templates 目录里两边各管各的。4.3 第三步用脚本串联模板做自动化流水线单个模板解决单个任务组合起来就是流水线。我在 CI 里做的最简单一条链路是代码审查 → 生成修复建议 → 生成测试 → 生成 commit 信息。# 1. 代码审查 review_result$(claude -p $(cat templates/code-review.md) --include src/** --output-format text) # 2. 把审查结果作为 refactoring 模板的输入 claude -p $(cat templates/refactoring.md) --context $review_result # 3. 生成测试 claude -p $(cat templates/test-generation.md) --include src/utils.py # 4. 生成提交信息 git diff HEAD | claude -p $(cat templates/commit-message.md)核心思路是“上一步的输出变成下一步的输入”。AI 本身没有上下文记忆但你可以通过变量和管道手动把上下文传递下去。这条链路跑起来之后代码从提交到审查到测试中间的人工重复劳动少了一大半。4.4 第四步模板版本的 Git 管理与回滚模板是会演化的。模型版本升级后某些模板块可能失效团队代码规范变化后审查重点也要调整。所以我把 templates 目录放在独立仓库里所有改动走 MRtemplate: code-review: 增加对日志脱敏的检查每次改动前我会先跑一遍旧模板在当前模型下的输出再跑一遍新模板对比差异。有回滚需求时直接 reset 到历史 commit 就行。这比“把模板存在某个在线文档里随手改”要可靠得多因为每次调整都有上下文可查。5. 常见问题与排查技巧实录5.1 模板加载了但 AI 就是不按格式走这是出现最多的问题。排查步骤按顺序来第一确认模板确实被加载了。用claude -p时可以把模板内容打印出来看一眼确认没有因为转义问题截断。我遇到过 sed 命令里符号被特殊处理导致整个模板被替换得面目全非。第二检查模板里是否同时存在“约束”和“示例”。AI 对抽象约束的理解不如对具体示例的理解。光写“使用 Markdown 表格输出”它可能理解成任意表格在后面加一行“示例| 阻塞 | src/a.py | 10 | 空指针风险 | 增加判空 |”基本不会再跑偏。第三把格式要求从模板中间挪到末尾。AI 有“近因效应”离输出格式最近的内容影响最大。这是用脚踩出来的经验。5.2 模板太长上下文窗口被吃掉一大半模板本身不能贪多。我最初写的代码审查模板有 120 行塞进上下文后AI 对代码本身的注意力明显下降审查质量反而不如短的。解决办法是分层把真正的背景知识和团队规范写进CLAUDE.md让 AI 常驻记忆模板里只放“本次任务必须要做的动作和输出格式”。例如角色的详细人设放 CLAUDE.md模板里只需要“你是一位资深后端工程师参见 CLAUDE.md 中的代码审查规范”。模板行数控制在 30~60 行为宜。超过 60 行建议拆分。上下文窗口是有限的每给模板多一个字就给代码少一个字——这句话我贴在所有模板文件的开头注释里。5.3 多语言项目里同一份模板失效我的项目是 Python、TypeScript、Go 混合仓库。最初一份代码审查模板跑三个语言结果 Python 的并发问题它不查 GIL、TypeScript 的异步错误处理它不查 Promise审查深度明显不够。解决方式模板里不写具体语言的检查项而是让变量去控制。{{language}}传入后AI 自己检索对应语言的常见问题类型。更稳一点的做法是为每个语言写一个code-review-python.md和code-review-ts.md共享角色和输出格式但“审查重点”完全分离。调用时在 alias 里加上语言参数review-pyclaude -p $(cat ~/templates/code-review-python.md) $ review-tsclaude -p $(cat ~/templates/code-review-ts.md) $5.4 模板库维护的避坑指南最后说几个容易忽略的细节。第一不要在模板里塞敏感信息。模板文件通常进 Git 仓库写死内部系统地址、密钥示例哪怕只是示例也会埋下隐患。所有环境相关的内容一律走变量。第二不要让模板数量失控。我见过有人攒了 40 多个模板最后自己都记不清哪个是哪个。我的习惯是控制在 8 个以内的高频模板低频场景直接用一句临时提示词解决不值得为它维护一个文件。第三每隔一段时间就要重新验证模板。Claude Code 底层的模型版本更新后同一句话的输出风格会变化。我通常是每个季度把所有模板在典型仓库上跑一遍检查输出质量和格式顺手更新失效的部分。第四模板一定要配示例输出。没有示例输出的模板就像没有测试用例的代码没人敢保证下一次还灵。我每个模板文件的最后都附一段“调用示例”和“期望输出片段”既是文档也是回归测试的依据。我自己在实际操作中的体会是claude-code-templates 的重点从来不是把提示词写得有多华丽而是让“告诉 AI 怎么干活”这件事本身变得可复用、可审计、可演进。你不需要追求模板的数量先把手头最高频的三五个任务模板化跑通之后自然会感受到差别。等攒到一定的量再回头去把这些模板按团队规范打磨一遍那才是它真正发挥价值的时候。