如果你已经在终端里和 Claude Code 打了几个月的交道大概会和我有同样的感觉模型能力很强但每次让它干同一类活儿都要重新说一遍上下文、重新交代一遍输出规范。后来我把这些反复重复的指令沉淀成了一个个模板文件做成了一套 claude-code-templates 仓库。这篇文章不打算重复官方文档里能查到的基础操作而是讲讲我从一套实际投入使用的模板仓库里踩出来的搭建思路、高频模板内容和调优经验适合正在用 Claude Code 写代码、做 code review、或者想给团队建立统一 AI 协作规范的开发者参考。1. 先把底子说清楚Claude Code 的模板机制到底解决了什么问题1.1 CLI 编程助手的记性差逼出了模板需求Claude Code 给人的第一印象是在终端里输入自然语言它就能帮你读代码、改文件、跑命令。但用的时间一长你会发现自己一直在重复三件很消耗精力的事第一反复交代项目背景。每次新开一个会话它对你的项目一无所知。你得告诉它这是一个 Python 后端仓库数据库用的是 PostgreSQL路由层在 app/api 目录下业务逻辑在 domain 目录下。短项目还好大一点的仓库光说清楚这些就要占好几个屏幕。第二反复约束输出格式。我需要它做代码审查时希望输出包含问题严重级别、文件行号、修改建议希望它写技术方案时先列约束条件再做方案对比。但这些偏好如果不写进每次对话它就会随心所欲地输出第一轮结果往往没法直接用。第三团队之间的协作标准不一致。同一个项目组里有人让它看看这段代码有人让它做一轮 code review同样是审查输出的深度和格式完全对不上。最后汇总的时候还得有人在中间做翻译。模板机制解决的就是这三件事把稳定不变的部分提前沉淀成文件把每次变化的部分留给命令参数。这就是 claude-code-templates 的核心价值——它不是一堆 prompt 的收藏夹而是把 AI 协作规范工程化的手段。我的实际感受是配上模板之后新会话的热身期大幅缩短第一轮结果的可直接用率提高很多。1.2 模板体系由哪几块组成Claude Code 的模板体系不是单一文件而是由四个互相配合的部分构成。我把它们整理成一张对照表方便你快速判断自己当前最缺哪一块组成部分存放位置解决什么问题典型场景CLAUDE.md项目根目录的 .claude/ 下或用户目录 ~/.claude/ 下项目级/用户级的长效记忆每次会话自动加载项目架构说明、代码规范、常用命令、禁止事项Slash Commands.claude/commands/*.md把固定指令封装成斜杠命令一个词触发一套完整工作流/review 发起代码审查/plan 生成技术方案/fix 修复指定问题Agent Skills.claude/skills/ /SKILL.md给模型注入某类任务的专业技能可附带脚本和参考文档代码审查技能、数据库迁移技能、依赖升级技能Hooks.claude/settings.json在模型执行动作前后自动触发脚本做硬性约束写文件前做敏感信息扫描、命令执行前做白名单校验这四个部分里最容易被忽略的是 Sovereign 关系CLAUDE.md 是背景知识Slash Commands 是标准操作流程Skills 是专业能力包Hooks 是强制守门员。打个比方CLAUDE.md 像入职手册Slash Commands 像审批流程模板Skills 像岗位技能认证Hooks 像门禁系统。我在实际使用中建议优先做 Slash Commands因为它的性价比最高——一个 .md 文件就能让整条工作流可复用不需要额外写脚本也不依赖复杂的触发配置。1.3 一套模板仓库应该被当成工程资产对待很多人把模板理解成几个写得还行的 markdown 文件我一开始也是这么想的后来吃了亏才改过来。真正好用的模板仓库应该像代码仓库一样被管理有清晰的目录结构有命名规范有版本记录有维护说明。原因很简单模板会演化。你不可能第一次就写出完美的 review 模板一定是用了几周之后发现它总是漏掉某个检查维度于是补上一段或者发现某条指令和项目里的 CLAUDE.md 冲突于是调整措辞。如果没有版本记录和变更日志一个月后你会面对一堆改得面目全非的文件根本记不清每个版本之间改了什么、为什么改。另一个原因是可迁移性。我在不同项目之间切换时会把模板仓库直接复制过去。有了结构化的文件夹和命名规范复制过去之后只需要微调项目相关的 CLAUDE.mdSlash Commands 和 Skills 基本可以原样复用。如果当初只是把模板零散地塞在项目里迁移成本就会高很多甚至要重新写一遍。2. 模板仓库怎么搭才不翻车目录结构与命名规范2.1 一套经得起长期维护的目录布局这是我目前在多个项目中用下来的目录结构经历了三轮迭代目前比较稳定claude-code-templates/ ├── README.md # 仓库说明模板怎么装、怎么用、怎么提改进 ├── project/ # 项目级模板复制到具体仓库的 .claude/ 下 │ ├── CLAUDE.md # 项目记忆主文件放架构、规范、命令 │ ├── commands/ # 自定义斜杠命令 │ │ ├── review.md │ │ ├── design.md │ │ ├── refactor.md │ │ ├── test.md │ │ └── onboard.md │ ├── skills/ # Agent 技能 │ │ ├── dependency-audit/ │ │ │ ├── SKILL.md │ │ │ └── scripts/ │ │ └── sql-review/ │ │ ├── SKILL.md │ │ └── rules/ │ └── settings.json # Hooks 等运行配置 ├── user/ # 用户级模板放到 ~/.claude/ 下 │ ├── CLAUDE.md # 个人偏好比如输出语言、常用工具链 │ └── commands/ # 跨项目通用命令 ├── fixtures/ # 供模板测试的小型示例项目 └── docs/ ├── template-style-guide.md # 模板写作规范 └── change-log.md # 模板版本变更记录这套结构的设计意图很明确把项目特定的内容和跨项目通用的内容分开。project/里的东西会跟着具体项目走比如某项目的模块划分、部署方式、代码规范user/里的东西跟着开发者个人走比如我习惯让 Claude 默认用中文回复技术解释、遇到不确定的信息明确标注此处存疑。两个层级叠在一起既不会让项目模板带上太多个人色彩也不会让个人偏好散落在各个项目里。2.2 命名与权限管理决定了团队协作的上限Slash Command 的文件名就是命令名比如.claude/commands/review.md在会话里对应/review。命名这件事看起来小实际上决定了一个团队能不能顺畅地用起来。我的建议是三条第一动词开头一个词最好。review、design、refactor、test、onboard这类命名看一眼就知道命令是干什么的。团队里如果有多个命名词性化比如code-review和review-flow同时存在很快就没人记得住。中文环境同理我用的是审查设计重构这类单动名词。第二低频命令加上场景限定。比如review是常规代码审查review-migration是专门审查数据库迁移脚本的。低频命令加限定词可以避免和高频命令混淆也方便在/help列表里快速区分。第三权限意识要提前做。Claude Code 模板文件里可以声明命令允许使用的工具这一点非常关键。比如我写 review 模板时只允许它读文件和 git 相关命令不允许它直接修改代码写 refactor 模板时才放开Edit、Write这类修改工具。这样即使团队成员误用了命令也不会因为模型自主调用了危险工具而闯祸。2.3 版本管理与变更记录模板仓库引入版本管理之后我养成了一个习惯每次改动模板都要在docs/change-log.md里记一行。格式很简单包含日期、改动文件、改动原因、影响范围## 2025-06-08 - review.md新增安全风险检查维度因为上次在依赖升级 PR 里漏掉了不安全的协议头 - CLAUDE.md更新测试命令说明统一用 make test 替代裸 pytest变更记录的价值在两周后就会体现出来。有一次我们团队觉得最近生成的测试质量下降了翻 change-log 才发现四天前为了处理某个特殊场景往 test 模板里加了一段尽量不 mock多写集成测试的指令结果影响面比预期大。于是很快定位到原因并做了回退。另外一个容易被忽视的点是模板测试。我在fixtures/里放了一个小型示例项目专门用来验证模板是否正常工作。每次新写或修改模板先到这个示例项目里跑一遍确认输出符合预期再复制到真实项目。没有这层验证很容易出现模板在真实项目里第一次跑就报错的尴尬状况尤其是涉及文件路径和目录扫描的模板。3. 五个我从实际项目中沉淀下来的高频模板3.1 review.md把代码审查标准写进命令这是整个仓库里使用频率最高的模板。它的结构经过了很多轮迭代目前长这样--- description: 对指定范围或文件做一轮代码审查 argument-hint: 分支名或文件路径 allowed-tools: Read, Grep, Glob, Bash(git) --- 对以下范围内的代码做一轮代码审查。 审查范围 $ARGUMENTS 审查必须覆盖以下维度 1. 正确性是否存在明显的逻辑错误、边界条件遗漏、并发问题 2. 安全性是否有注入风险、敏感信息泄露、不安全的反序列化 3. 可维护性命名是否清晰、函数是否过长、是否存在重复代码 4. 性能是否有明显的低效路径比如循环内反复查询数据库 5. 测试覆盖高风险逻辑是否有对应测试 输出格式 - 按严重级别分组阻塞 / 建议 / 非阻塞 - 每条问题必须给出文件路径 行号 问题描述 修改建议 - 严重级别为阻塞的问题必须给出最小复现场景 - 最后输出一段 200 字以内的总体评价先讲优点再讲问题这个模板能稳定工作的关键是allowed-tools 只给了读权限和 git 命令。审查本质上是只读操作如果给它写权限它很容易在发现问题的同时顺手改了代码最后 PR 里混进一堆不属于本次审查的改动review 的价值就被破坏了。另外我特意要求最后先讲优点再讲问题这是从团队协作角度设计的——审查结果如果一上来全是负面问题接收方容易产生防御心理。3.2 design.md让技术方案先约束再发散写技术方案是 Claude Code 很强、也最容易跑偏的场景。没有约束时它倾向于直接给出一个看似完整的方案但对约束条件、备选方案、取舍逻辑交代得很少。我的 design 模板强制它按固定顺序思考--- description: 生成一份技术方案文档 argument-hint: 简短描述要解决的问题 --- 针对以下需求产出一份技术方案文档 需求$ARGUMENTS 文档必须按以下结构组织 1. 需求背景与问题定义 - 用 3-5 句话说明要解决什么问题不包含解决方案细节 2. 硬性约束与不可妥协条件 - 技术栈限制、性能指标、部署环境、兼容性要求 - 如果需求描述里没有明确给出请列出待确认约束清单 3. 候选方案列表至少 2 个 - 每个方案给出核心思路、改动范围、预估工作量、主要风险 4. 方案对比与推荐 - 对比维度实现成本、维护成本、性能风险、团队熟悉度 - 明确给出推荐方案并说明一票否决了哪些方案、为什么 5. 实施计划与验收标准 - 分阶段列出改动步骤每步给出可验证的完成标准我设计这个模板时最强调的一点是**先约束再发散**。很多无效方案的产生不是模型想不到好方案而是它在没有搞清楚约束条件的情况下就开始发散。加上了硬性约束这一步之后生成的方案明显更落地。推荐方案那个环节也很关键我要求它必须说明否决了哪些方案这个设计能让它把思考过程暴露出来而不是只给结论。3.3 refactor.md重构前先交影响面清单重构是风险最高的 AI 协作场景之一因为模型修改代码后原行为是否保持不变它自己是无法完整验证的。所以 refactor 模板的核心设计思路是安全垫--- description: 对指定模块做行为保持的重构 argument-hint: 模块路径或文件路径 allowed-tools: Read, Grep, Glob, Edit, Bash --- 对以下模块做重构要求行为保持不变 目标$ARGUMENTS 第一步影响面分析 - 列出该模块的调用方、依赖方、外部接口 - 标记高风险区域公共 API、跨模块依赖、序列化边界 第二步行为基线确认 - 先给出当前行为的特征描述输入输出、边界条件、异常处理 - 如有可能建议可执行的基线测试方式 第三步重构实施 - 分小步进行每一步做一次完整编译/测试 - 任何一步出现失败立即停止并回退最近一步 第四步验证与回归 - 对比重构前后的关键行为特征 - 输出验证结果编译状态、测试通过率、已知差异清单用这个模板之后我最明显的感受是模型不再一口气改完全部了而是会主动分步执行每一步停下来等测试结果。原因很简单模板里明确写了任何一步出现失败立即停止并回退最近一步这个指令会强烈影响它的工具调用模式。如果你也遇到过重构到一半发现项目已经跑不起来的情况可以优先试试这个模板哪怕只是把分步执行的指令抄过去也能改善很多。3.4 test.md测试生成模板的 Mock 边界Claude Code 写测试的能力不错但有两个老毛病一是过度 mock把本该验证真实行为的逻辑全 mock 掉了测试变成自问自答二是断言写得过于宽松断言response.status_code 200却不去检查响应内容结构。test 模板就是针对这两个毛病设计的--- description: 为指定模块生成单元测试或集成测试 argument-hint: 模块路径或函数名 --- 为以下目标生成测试代码 目标$ARGUMENTS 约束 1. Mock 边界控制 - 只允许 mock外部服务调用、IO 读写、时钟/随机数 - 禁止 mock被测函数内部的核心逻辑分支 - 对每个 mock在注释里说明为什么不测真实实现 2. 断言标准 - 状态码断言之外必须断言响应体结构的关键字段 - 对列表/集合结果同时断言数量与元素关键属性 - 异常分支必须断言错误类型与错误信息内容 3. 测试命名与组织 - 使用 given_when_then 风格的测试名 - 每个测试只验证一个行为点 - 超过 10 行初始化代码的先抽取 fixtureMock 边界这条约束是经过几次失败的测试审查后总结出来的。有一回模型为了提升测试覆盖率把内部函数返回值全部 mock 成固定值测试看起来绿得漂亮但真实代码路径根本没执行换个输入就崩。加了禁止 mock 被测函数内部核心逻辑分支之后这种自欺欺人的测试少了很多。3.5 onboard.md新项目秒变老熟人最后这个模板不是为 AI 写的更像是为新加入 AI 协作环境的人准备的。它的目标是当你把一个新仓库交给 Claude Code 时不再需要手动解释项目背景而是让模型自己按顺序把关键信息读出来并产出结构化的认知文档--- description: 快速理解一个新项目的架构与约定 argument-hint: 项目根路径默认当前目录 --- 请完成对一个新项目的快速调研按顺序执行 1. 读取项目入口文件README、pyproject.toml / package.json / Cargo.toml 等 2. 扫描顶层目录结构识别模块边界 3. 定位路由/接口定义层、数据模型层、业务逻辑层 4. 查找自动化测试的位置与运行方式 5. 识别项目特有的代码约定命名风格、错误处理模式 最终输出 - 一段 100 字以内的项目定位描述 - 目录结构速览只画主要模块控制在 12 行以内 - 核心技术栈清单 - 常见任务的入口文件列表如新增 API 需要动哪里 - 项目特有约定的清单以及需要向维护者确认的疑问列表onboard 模板是我在接手一个新仓库时用的第一个命令。它产出的疑问列表尤其有价值——真实的项目里总有文档没写清楚、代码里也看不出来的隐藏约定让模型把这些问题集中列出来下一步再带着这些问题去问维护者比漫无目的地翻代码高效得多。4. 模板调优的几条硬经验为什么你的模板经常失灵4.1 变量与上下文隔离的坑Claude Code 的模板支持$ARGUMENTS获取整个参数串和$1、$2位置参数。我实际用下来有几个很具体的坑第一个坑是参数长度与格式保持。如果你在会话里输入/review src/core src/utils模板里的$ARGUMENTS拿到的是原始字符串这可能带有多余空格或换行。我的做法是在模板里尽快做一次归一化比如明确写对参数中的每个路径逐个处理忽略空行与多余空格这能省掉很多因为参数格式问题导致的歧义。第二个坑是工作目录漂移。模板在执行过程中如果触发模型去跑命令当前工作目录可能和会话起始目录不一致尤其是接了 hooks 之后。我的规避方式有两层一是在模板开头显式声明所有相对路径都相对于项目根目录先执行 pwd 确认当前路径二是在 design 这类模板里要求模型在动手前用 ls 确认目标目录存在。听起来基础但很多模板失灵其实就是路径问题。第三个坑是环境变量泄漏。不要试图在模板里硬编码任何密钥或主机地址。模板文件通常放在 git 仓库里一旦提交到远程历史上删掉的文件也可能留在 git 历史里。我的原则是模板里只写占位符比如$DEPLOY_HOST实际值通过环境变量注入Hooks 里做校验。这样既灵活又安全。4.2 模板不是越长越好我最早写 review 模板的时候列了十二个检查维度每个维度下面还有两到三行解释总字数将近两千。跑出来的结果让我很意外模型确实照着做了但它把精力分散在大量维度上每个维度都浅尝辄止反而不如后来精简版的效果好。后来我做了一个对比实验同一个文件分别用 1800 字的长模板和 400 字的短模板做 review。长模板输出覆盖面广但深度不足很多条目像是在凑数短模板聚焦在正确性、安全性、可维护性五个维度上每个维度都给到了具体行号和可执行的修改建议。这个实验让我确定了模板写作的一条原则能用清单式短句说清楚的绝不用散文。模板里每多一句话模型就会多一个可以考虑的对象指令之间的优先级会被稀释。我现在的模板几乎全是短句和动作列表即使加上输出格式约束单个模板也控制在 600 字以内。如果你发现模板生效了但效果平平第一步不是加内容而是删内容。4.3 CLAUDE.md 的层级加载机制与常见误解CLAUDE.md 的加载机制是层级式的企业级配置在最上层然后是你个人目录~/.claude/CLAUDE.md再往下是项目根目录的.claude/CLAUDE.md最后是子目录里的CLAUDE.md。子目录的 CLAUDE.md 通常只会影响该目录及其子目录下的会话上下文。这里有一个常见的误解以为后加载的 CLAUDE.md 会覆盖先加载的。实际上我实测下来不同层级的 CLAUDE.md 是拼接在上下文里的而不是互相覆盖。如果个人 CLAUDE.md 里写默认用中文解释项目 CLAUDE.md 里写所有解释用英文并附中文术语表模型很可能把两者混合执行而不是严格按后加载的规则来。所以我的建议是不要把覆盖寄托在加载顺序上要在模板和 CLAUDE.md 里显式消解冲突。比如项目模板里直接声明本项目要求所有技术解释使用英文术语 中文说明与个人配置冲突时以此为准。模型对显式指令的遵循度远高于对隐性加载顺序的推断。这是我踩过几次坑之后总结出来的很值得记住。4.4 把反馈循环设计进模板模板不是写完就完事的它是需要迭代的活物。我总结了一个让模板自我进化的方法在模板末尾加上一段输出自评类似这样输出完成后请用三句话自评本次输出质量 - 哪个步骤消耗了最多上下文 - 有哪些信息是我本应该主动询问但没问的 - 如果下次执行模板里哪条指令最应该调整不要小看这段自评。它每次执行时都会把模型执行过程中的阻塞点暴露出来而这些阻塞点正是模板需要改进的地方。有次 test 模板频繁生成低质量测试自评里反复出现我不确定该模块的 mock 边界因为 CLAUDE.md 里没有说明外部服务依赖我这才意识到问题是缺一段项目背景说明而不是模板指令不对。我建议每两周做一次模板回顾把最近所有自评内容扫一遍找出反复出现的三个关键词然后针对性地修订模板。这比凭感觉判断模板好坏可靠得多。模板维护的本质就是一个持续反馈循环自评设计是这个循环的传感器。5. 实测对比与效果复盘有模板和没有模板的差别5.1 同一需求两种模式下的执行质量对比我用一个真实需求做了对比测试让 Claude Code 给一个 FastAPI 项目新增一个用户收藏商品的接口包含数据模型、接口、测试。一轮是无模板直接对话一轮使用 design 和 test 两个模板配合。以下是我记录下来的主观评估对比维度无模板直聊使用模板流程背景交代耗时约 8 分钟手动描述项目结构约 1 分钟模板自动补齐上下文方案质量直接给出单一实现方案先列两条候选方案再给推荐与理由改动完整性数据模型和路由写了测试缺失模型、路由、测试、迁移脚本均覆盖输出可用率第一轮通过率约 50%需要多次追问第一轮通过率约 80%小改动即可落库代码风格一致性与既有代码风格有出入需人工调整基本沿用项目既有命名与错误处理模式这个对比是在我自己的项目里做的数据不算严谨但趋势非常一致模板最大的收益不是让 AI 变聪明而是大幅降低上下文切换成本和无谓的反复沟通。没有模板时很多时间花在补背景、纠格式、追缺失上有模板后这些环节被前置到了文件里会话一开始就在正确的轨道上。5.2 模板失效的坏味道清单即使模板写得不错也难免遇到模板生效了但结果不对劲的情况。我整理了一份排查清单按出现频率排序输出像没看到模板先检查命令名是否真的触发了模板而不是撞上了普通对话。输入/review却没任何反应大概率是文件名放错位置或大小写写错。模板执行了但格式不遵守最常见的原因是模板里同时给了太多优先级不明的指令。解决办法是压缩指令数量把最硬性的输出格式放在最后一段并明确写这是最终输出格式不要额外包装。工具调用次序混乱模板说先分析影响面再修改但模型直接动手改了。这是 allowed-tools 设置过宽的表现。给模板加上分阶段工具权限比如重构第一步只允许读命令能有效约束次序。路徑与目录相关指令反复失效优先排查是否写死了绝对路径以及模板是否要求模型先 pwd/globl 确认目录存在。输出正确但内容飘模板和 CLAUDE.md 之间出现隐性冲突按 4.3 节的方法显式声明优先级。这个清单不是一次性列出来的而是我经历了各种明明按模板写了结果却不符合预期的场景后逐条积累的。你可以在自己团队里建立类似的故障档案每次排查完把原因补进去。5.3 后续扩展方向Hooks 与 Skills 的联动空间模板仓库做到这一步基本已经能覆盖日常开发里七八成的重复任务。再往后扩展我建议把触角伸到 Hooks 和 Skills 的联动上。Hooks 的价值在于硬性守门。比如我在一个涉及支付模块的项目里加了一个 PreToolUse Hook在模型执行Bash(git push)之前先扫描本次变更里是否包含密钥文件一旦命中立即拦截。这类检查如果只写在模板里属于软约束模型可能因为注意力漂移而忽略写在 Hook 里就是不管模型怎么想都必须执行的规则。Skills 则适合沉淀低频但复杂的专业能力。比如数据库索引审查、Kubernetes 配置校验、前端依赖安全审计这些任务每次执行都需要加载大量专业规则不适合塞进 Slash Command。把它们做成 SKILL.md 放在 .claude/skills/ 下模型会在匹配到相关任务时自动加载对应能力包比手动/command更自然。我目前的一个扩展方向是把项目里累积的线上故障案例做成一个 skill包含常见的故障模式、排查路径、应急处理脚本。这样下次再遇到相似问题时Claude Code 能被 skill 引导着更像一个经历过这类故障的老手而不是刚入行的实习生。从第一次把零散的 prompt 整理成模板仓库开始这个项目已经跟着我换过三个代码仓库迭代了十几轮。我现在最大的体会是模板真正管理的不是 AI而是团队协作的约定。把审查标准、设计规范、测试边界这些隐性知识写进模板等于让每个参与项目的人——无论是人还是 AI——都站在同一条起跑线上。未来这个仓库还会继续扩可能是更多专业领域的 skill也可能是和团队知识库打通让 AI 协作的边界再往前推一步。 
长河君 · 2026/10/17 4:06:33 · 阅读 1.2k 从模板仓库实践看Claude Code：让AI协作规范工程化落地
如果你已经在终端里和 Claude Code 打了几个月的交道大概会和我有同样的感觉模型能力很强但每次让它干同一类活儿都要重新说一遍上下文、重新交代一遍输出规范。后来我把这些反复重复的指令沉淀成了一个个模板文件做成了一套 claude-code-templates 仓库。这篇文章不打算重复官方文档里能查到的基础操作而是讲讲我从一套实际投入使用的模板仓库里踩出来的搭建思路、高频模板内容和调优经验适合正在用 Claude Code 写代码、做 code review、或者想给团队建立统一 AI 协作规范的开发者参考。1. 先把底子说清楚Claude Code 的模板机制到底解决了什么问题1.1 CLI 编程助手的记性差逼出了模板需求Claude Code 给人的第一印象是在终端里输入自然语言它就能帮你读代码、改文件、跑命令。但用的时间一长你会发现自己一直在重复三件很消耗精力的事第一反复交代项目背景。每次新开一个会话它对你的项目一无所知。你得告诉它这是一个 Python 后端仓库数据库用的是 PostgreSQL路由层在 app/api 目录下业务逻辑在 domain 目录下。短项目还好大一点的仓库光说清楚这些就要占好几个屏幕。第二反复约束输出格式。我需要它做代码审查时希望输出包含问题严重级别、文件行号、修改建议希望它写技术方案时先列约束条件再做方案对比。但这些偏好如果不写进每次对话它就会随心所欲地输出第一轮结果往往没法直接用。第三团队之间的协作标准不一致。同一个项目组里有人让它看看这段代码有人让它做一轮 code review同样是审查输出的深度和格式完全对不上。最后汇总的时候还得有人在中间做翻译。模板机制解决的就是这三件事把稳定不变的部分提前沉淀成文件把每次变化的部分留给命令参数。这就是 claude-code-templates 的核心价值——它不是一堆 prompt 的收藏夹而是把 AI 协作规范工程化的手段。我的实际感受是配上模板之后新会话的热身期大幅缩短第一轮结果的可直接用率提高很多。1.2 模板体系由哪几块组成Claude Code 的模板体系不是单一文件而是由四个互相配合的部分构成。我把它们整理成一张对照表方便你快速判断自己当前最缺哪一块组成部分存放位置解决什么问题典型场景CLAUDE.md项目根目录的 .claude/ 下或用户目录 ~/.claude/ 下项目级/用户级的长效记忆每次会话自动加载项目架构说明、代码规范、常用命令、禁止事项Slash Commands.claude/commands/*.md把固定指令封装成斜杠命令一个词触发一套完整工作流/review 发起代码审查/plan 生成技术方案/fix 修复指定问题Agent Skills.claude/skills/ /SKILL.md给模型注入某类任务的专业技能可附带脚本和参考文档代码审查技能、数据库迁移技能、依赖升级技能Hooks.claude/settings.json在模型执行动作前后自动触发脚本做硬性约束写文件前做敏感信息扫描、命令执行前做白名单校验这四个部分里最容易被忽略的是 Sovereign 关系CLAUDE.md 是背景知识Slash Commands 是标准操作流程Skills 是专业能力包Hooks 是强制守门员。打个比方CLAUDE.md 像入职手册Slash Commands 像审批流程模板Skills 像岗位技能认证Hooks 像门禁系统。我在实际使用中建议优先做 Slash Commands因为它的性价比最高——一个 .md 文件就能让整条工作流可复用不需要额外写脚本也不依赖复杂的触发配置。1.3 一套模板仓库应该被当成工程资产对待很多人把模板理解成几个写得还行的 markdown 文件我一开始也是这么想的后来吃了亏才改过来。真正好用的模板仓库应该像代码仓库一样被管理有清晰的目录结构有命名规范有版本记录有维护说明。原因很简单模板会演化。你不可能第一次就写出完美的 review 模板一定是用了几周之后发现它总是漏掉某个检查维度于是补上一段或者发现某条指令和项目里的 CLAUDE.md 冲突于是调整措辞。如果没有版本记录和变更日志一个月后你会面对一堆改得面目全非的文件根本记不清每个版本之间改了什么、为什么改。另一个原因是可迁移性。我在不同项目之间切换时会把模板仓库直接复制过去。有了结构化的文件夹和命名规范复制过去之后只需要微调项目相关的 CLAUDE.mdSlash Commands 和 Skills 基本可以原样复用。如果当初只是把模板零散地塞在项目里迁移成本就会高很多甚至要重新写一遍。2. 模板仓库怎么搭才不翻车目录结构与命名规范2.1 一套经得起长期维护的目录布局这是我目前在多个项目中用下来的目录结构经历了三轮迭代目前比较稳定claude-code-templates/ ├── README.md # 仓库说明模板怎么装、怎么用、怎么提改进 ├── project/ # 项目级模板复制到具体仓库的 .claude/ 下 │ ├── CLAUDE.md # 项目记忆主文件放架构、规范、命令 │ ├── commands/ # 自定义斜杠命令 │ │ ├── review.md │ │ ├── design.md │ │ ├── refactor.md │ │ ├── test.md │ │ └── onboard.md │ ├── skills/ # Agent 技能 │ │ ├── dependency-audit/ │ │ │ ├── SKILL.md │ │ │ └── scripts/ │ │ └── sql-review/ │ │ ├── SKILL.md │ │ └── rules/ │ └── settings.json # Hooks 等运行配置 ├── user/ # 用户级模板放到 ~/.claude/ 下 │ ├── CLAUDE.md # 个人偏好比如输出语言、常用工具链 │ └── commands/ # 跨项目通用命令 ├── fixtures/ # 供模板测试的小型示例项目 └── docs/ ├── template-style-guide.md # 模板写作规范 └── change-log.md # 模板版本变更记录这套结构的设计意图很明确把项目特定的内容和跨项目通用的内容分开。project/里的东西会跟着具体项目走比如某项目的模块划分、部署方式、代码规范user/里的东西跟着开发者个人走比如我习惯让 Claude 默认用中文回复技术解释、遇到不确定的信息明确标注此处存疑。两个层级叠在一起既不会让项目模板带上太多个人色彩也不会让个人偏好散落在各个项目里。2.2 命名与权限管理决定了团队协作的上限Slash Command 的文件名就是命令名比如.claude/commands/review.md在会话里对应/review。命名这件事看起来小实际上决定了一个团队能不能顺畅地用起来。我的建议是三条第一动词开头一个词最好。review、design、refactor、test、onboard这类命名看一眼就知道命令是干什么的。团队里如果有多个命名词性化比如code-review和review-flow同时存在很快就没人记得住。中文环境同理我用的是审查设计重构这类单动名词。第二低频命令加上场景限定。比如review是常规代码审查review-migration是专门审查数据库迁移脚本的。低频命令加限定词可以避免和高频命令混淆也方便在/help列表里快速区分。第三权限意识要提前做。Claude Code 模板文件里可以声明命令允许使用的工具这一点非常关键。比如我写 review 模板时只允许它读文件和 git 相关命令不允许它直接修改代码写 refactor 模板时才放开Edit、Write这类修改工具。这样即使团队成员误用了命令也不会因为模型自主调用了危险工具而闯祸。2.3 版本管理与变更记录模板仓库引入版本管理之后我养成了一个习惯每次改动模板都要在docs/change-log.md里记一行。格式很简单包含日期、改动文件、改动原因、影响范围## 2025-06-08 - review.md新增安全风险检查维度因为上次在依赖升级 PR 里漏掉了不安全的协议头 - CLAUDE.md更新测试命令说明统一用 make test 替代裸 pytest变更记录的价值在两周后就会体现出来。有一次我们团队觉得最近生成的测试质量下降了翻 change-log 才发现四天前为了处理某个特殊场景往 test 模板里加了一段尽量不 mock多写集成测试的指令结果影响面比预期大。于是很快定位到原因并做了回退。另外一个容易被忽视的点是模板测试。我在fixtures/里放了一个小型示例项目专门用来验证模板是否正常工作。每次新写或修改模板先到这个示例项目里跑一遍确认输出符合预期再复制到真实项目。没有这层验证很容易出现模板在真实项目里第一次跑就报错的尴尬状况尤其是涉及文件路径和目录扫描的模板。3. 五个我从实际项目中沉淀下来的高频模板3.1 review.md把代码审查标准写进命令这是整个仓库里使用频率最高的模板。它的结构经过了很多轮迭代目前长这样--- description: 对指定范围或文件做一轮代码审查 argument-hint: 分支名或文件路径 allowed-tools: Read, Grep, Glob, Bash(git) --- 对以下范围内的代码做一轮代码审查。 审查范围 $ARGUMENTS 审查必须覆盖以下维度 1. 正确性是否存在明显的逻辑错误、边界条件遗漏、并发问题 2. 安全性是否有注入风险、敏感信息泄露、不安全的反序列化 3. 可维护性命名是否清晰、函数是否过长、是否存在重复代码 4. 性能是否有明显的低效路径比如循环内反复查询数据库 5. 测试覆盖高风险逻辑是否有对应测试 输出格式 - 按严重级别分组阻塞 / 建议 / 非阻塞 - 每条问题必须给出文件路径 行号 问题描述 修改建议 - 严重级别为阻塞的问题必须给出最小复现场景 - 最后输出一段 200 字以内的总体评价先讲优点再讲问题这个模板能稳定工作的关键是allowed-tools 只给了读权限和 git 命令。审查本质上是只读操作如果给它写权限它很容易在发现问题的同时顺手改了代码最后 PR 里混进一堆不属于本次审查的改动review 的价值就被破坏了。另外我特意要求最后先讲优点再讲问题这是从团队协作角度设计的——审查结果如果一上来全是负面问题接收方容易产生防御心理。3.2 design.md让技术方案先约束再发散写技术方案是 Claude Code 很强、也最容易跑偏的场景。没有约束时它倾向于直接给出一个看似完整的方案但对约束条件、备选方案、取舍逻辑交代得很少。我的 design 模板强制它按固定顺序思考--- description: 生成一份技术方案文档 argument-hint: 简短描述要解决的问题 --- 针对以下需求产出一份技术方案文档 需求$ARGUMENTS 文档必须按以下结构组织 1. 需求背景与问题定义 - 用 3-5 句话说明要解决什么问题不包含解决方案细节 2. 硬性约束与不可妥协条件 - 技术栈限制、性能指标、部署环境、兼容性要求 - 如果需求描述里没有明确给出请列出待确认约束清单 3. 候选方案列表至少 2 个 - 每个方案给出核心思路、改动范围、预估工作量、主要风险 4. 方案对比与推荐 - 对比维度实现成本、维护成本、性能风险、团队熟悉度 - 明确给出推荐方案并说明一票否决了哪些方案、为什么 5. 实施计划与验收标准 - 分阶段列出改动步骤每步给出可验证的完成标准我设计这个模板时最强调的一点是**先约束再发散**。很多无效方案的产生不是模型想不到好方案而是它在没有搞清楚约束条件的情况下就开始发散。加上了硬性约束这一步之后生成的方案明显更落地。推荐方案那个环节也很关键我要求它必须说明否决了哪些方案这个设计能让它把思考过程暴露出来而不是只给结论。3.3 refactor.md重构前先交影响面清单重构是风险最高的 AI 协作场景之一因为模型修改代码后原行为是否保持不变它自己是无法完整验证的。所以 refactor 模板的核心设计思路是安全垫--- description: 对指定模块做行为保持的重构 argument-hint: 模块路径或文件路径 allowed-tools: Read, Grep, Glob, Edit, Bash --- 对以下模块做重构要求行为保持不变 目标$ARGUMENTS 第一步影响面分析 - 列出该模块的调用方、依赖方、外部接口 - 标记高风险区域公共 API、跨模块依赖、序列化边界 第二步行为基线确认 - 先给出当前行为的特征描述输入输出、边界条件、异常处理 - 如有可能建议可执行的基线测试方式 第三步重构实施 - 分小步进行每一步做一次完整编译/测试 - 任何一步出现失败立即停止并回退最近一步 第四步验证与回归 - 对比重构前后的关键行为特征 - 输出验证结果编译状态、测试通过率、已知差异清单用这个模板之后我最明显的感受是模型不再一口气改完全部了而是会主动分步执行每一步停下来等测试结果。原因很简单模板里明确写了任何一步出现失败立即停止并回退最近一步这个指令会强烈影响它的工具调用模式。如果你也遇到过重构到一半发现项目已经跑不起来的情况可以优先试试这个模板哪怕只是把分步执行的指令抄过去也能改善很多。3.4 test.md测试生成模板的 Mock 边界Claude Code 写测试的能力不错但有两个老毛病一是过度 mock把本该验证真实行为的逻辑全 mock 掉了测试变成自问自答二是断言写得过于宽松断言response.status_code 200却不去检查响应内容结构。test 模板就是针对这两个毛病设计的--- description: 为指定模块生成单元测试或集成测试 argument-hint: 模块路径或函数名 --- 为以下目标生成测试代码 目标$ARGUMENTS 约束 1. Mock 边界控制 - 只允许 mock外部服务调用、IO 读写、时钟/随机数 - 禁止 mock被测函数内部的核心逻辑分支 - 对每个 mock在注释里说明为什么不测真实实现 2. 断言标准 - 状态码断言之外必须断言响应体结构的关键字段 - 对列表/集合结果同时断言数量与元素关键属性 - 异常分支必须断言错误类型与错误信息内容 3. 测试命名与组织 - 使用 given_when_then 风格的测试名 - 每个测试只验证一个行为点 - 超过 10 行初始化代码的先抽取 fixtureMock 边界这条约束是经过几次失败的测试审查后总结出来的。有一回模型为了提升测试覆盖率把内部函数返回值全部 mock 成固定值测试看起来绿得漂亮但真实代码路径根本没执行换个输入就崩。加了禁止 mock 被测函数内部核心逻辑分支之后这种自欺欺人的测试少了很多。3.5 onboard.md新项目秒变老熟人最后这个模板不是为 AI 写的更像是为新加入 AI 协作环境的人准备的。它的目标是当你把一个新仓库交给 Claude Code 时不再需要手动解释项目背景而是让模型自己按顺序把关键信息读出来并产出结构化的认知文档--- description: 快速理解一个新项目的架构与约定 argument-hint: 项目根路径默认当前目录 --- 请完成对一个新项目的快速调研按顺序执行 1. 读取项目入口文件README、pyproject.toml / package.json / Cargo.toml 等 2. 扫描顶层目录结构识别模块边界 3. 定位路由/接口定义层、数据模型层、业务逻辑层 4. 查找自动化测试的位置与运行方式 5. 识别项目特有的代码约定命名风格、错误处理模式 最终输出 - 一段 100 字以内的项目定位描述 - 目录结构速览只画主要模块控制在 12 行以内 - 核心技术栈清单 - 常见任务的入口文件列表如新增 API 需要动哪里 - 项目特有约定的清单以及需要向维护者确认的疑问列表onboard 模板是我在接手一个新仓库时用的第一个命令。它产出的疑问列表尤其有价值——真实的项目里总有文档没写清楚、代码里也看不出来的隐藏约定让模型把这些问题集中列出来下一步再带着这些问题去问维护者比漫无目的地翻代码高效得多。4. 模板调优的几条硬经验为什么你的模板经常失灵4.1 变量与上下文隔离的坑Claude Code 的模板支持$ARGUMENTS获取整个参数串和$1、$2位置参数。我实际用下来有几个很具体的坑第一个坑是参数长度与格式保持。如果你在会话里输入/review src/core src/utils模板里的$ARGUMENTS拿到的是原始字符串这可能带有多余空格或换行。我的做法是在模板里尽快做一次归一化比如明确写对参数中的每个路径逐个处理忽略空行与多余空格这能省掉很多因为参数格式问题导致的歧义。第二个坑是工作目录漂移。模板在执行过程中如果触发模型去跑命令当前工作目录可能和会话起始目录不一致尤其是接了 hooks 之后。我的规避方式有两层一是在模板开头显式声明所有相对路径都相对于项目根目录先执行 pwd 确认当前路径二是在 design 这类模板里要求模型在动手前用 ls 确认目标目录存在。听起来基础但很多模板失灵其实就是路径问题。第三个坑是环境变量泄漏。不要试图在模板里硬编码任何密钥或主机地址。模板文件通常放在 git 仓库里一旦提交到远程历史上删掉的文件也可能留在 git 历史里。我的原则是模板里只写占位符比如$DEPLOY_HOST实际值通过环境变量注入Hooks 里做校验。这样既灵活又安全。4.2 模板不是越长越好我最早写 review 模板的时候列了十二个检查维度每个维度下面还有两到三行解释总字数将近两千。跑出来的结果让我很意外模型确实照着做了但它把精力分散在大量维度上每个维度都浅尝辄止反而不如后来精简版的效果好。后来我做了一个对比实验同一个文件分别用 1800 字的长模板和 400 字的短模板做 review。长模板输出覆盖面广但深度不足很多条目像是在凑数短模板聚焦在正确性、安全性、可维护性五个维度上每个维度都给到了具体行号和可执行的修改建议。这个实验让我确定了模板写作的一条原则能用清单式短句说清楚的绝不用散文。模板里每多一句话模型就会多一个可以考虑的对象指令之间的优先级会被稀释。我现在的模板几乎全是短句和动作列表即使加上输出格式约束单个模板也控制在 600 字以内。如果你发现模板生效了但效果平平第一步不是加内容而是删内容。4.3 CLAUDE.md 的层级加载机制与常见误解CLAUDE.md 的加载机制是层级式的企业级配置在最上层然后是你个人目录~/.claude/CLAUDE.md再往下是项目根目录的.claude/CLAUDE.md最后是子目录里的CLAUDE.md。子目录的 CLAUDE.md 通常只会影响该目录及其子目录下的会话上下文。这里有一个常见的误解以为后加载的 CLAUDE.md 会覆盖先加载的。实际上我实测下来不同层级的 CLAUDE.md 是拼接在上下文里的而不是互相覆盖。如果个人 CLAUDE.md 里写默认用中文解释项目 CLAUDE.md 里写所有解释用英文并附中文术语表模型很可能把两者混合执行而不是严格按后加载的规则来。所以我的建议是不要把覆盖寄托在加载顺序上要在模板和 CLAUDE.md 里显式消解冲突。比如项目模板里直接声明本项目要求所有技术解释使用英文术语 中文说明与个人配置冲突时以此为准。模型对显式指令的遵循度远高于对隐性加载顺序的推断。这是我踩过几次坑之后总结出来的很值得记住。4.4 把反馈循环设计进模板模板不是写完就完事的它是需要迭代的活物。我总结了一个让模板自我进化的方法在模板末尾加上一段输出自评类似这样输出完成后请用三句话自评本次输出质量 - 哪个步骤消耗了最多上下文 - 有哪些信息是我本应该主动询问但没问的 - 如果下次执行模板里哪条指令最应该调整不要小看这段自评。它每次执行时都会把模型执行过程中的阻塞点暴露出来而这些阻塞点正是模板需要改进的地方。有次 test 模板频繁生成低质量测试自评里反复出现我不确定该模块的 mock 边界因为 CLAUDE.md 里没有说明外部服务依赖我这才意识到问题是缺一段项目背景说明而不是模板指令不对。我建议每两周做一次模板回顾把最近所有自评内容扫一遍找出反复出现的三个关键词然后针对性地修订模板。这比凭感觉判断模板好坏可靠得多。模板维护的本质就是一个持续反馈循环自评设计是这个循环的传感器。5. 实测对比与效果复盘有模板和没有模板的差别5.1 同一需求两种模式下的执行质量对比我用一个真实需求做了对比测试让 Claude Code 给一个 FastAPI 项目新增一个用户收藏商品的接口包含数据模型、接口、测试。一轮是无模板直接对话一轮使用 design 和 test 两个模板配合。以下是我记录下来的主观评估对比维度无模板直聊使用模板流程背景交代耗时约 8 分钟手动描述项目结构约 1 分钟模板自动补齐上下文方案质量直接给出单一实现方案先列两条候选方案再给推荐与理由改动完整性数据模型和路由写了测试缺失模型、路由、测试、迁移脚本均覆盖输出可用率第一轮通过率约 50%需要多次追问第一轮通过率约 80%小改动即可落库代码风格一致性与既有代码风格有出入需人工调整基本沿用项目既有命名与错误处理模式这个对比是在我自己的项目里做的数据不算严谨但趋势非常一致模板最大的收益不是让 AI 变聪明而是大幅降低上下文切换成本和无谓的反复沟通。没有模板时很多时间花在补背景、纠格式、追缺失上有模板后这些环节被前置到了文件里会话一开始就在正确的轨道上。5.2 模板失效的坏味道清单即使模板写得不错也难免遇到模板生效了但结果不对劲的情况。我整理了一份排查清单按出现频率排序输出像没看到模板先检查命令名是否真的触发了模板而不是撞上了普通对话。输入/review却没任何反应大概率是文件名放错位置或大小写写错。模板执行了但格式不遵守最常见的原因是模板里同时给了太多优先级不明的指令。解决办法是压缩指令数量把最硬性的输出格式放在最后一段并明确写这是最终输出格式不要额外包装。工具调用次序混乱模板说先分析影响面再修改但模型直接动手改了。这是 allowed-tools 设置过宽的表现。给模板加上分阶段工具权限比如重构第一步只允许读命令能有效约束次序。路徑与目录相关指令反复失效优先排查是否写死了绝对路径以及模板是否要求模型先 pwd/globl 确认目录存在。输出正确但内容飘模板和 CLAUDE.md 之间出现隐性冲突按 4.3 节的方法显式声明优先级。这个清单不是一次性列出来的而是我经历了各种明明按模板写了结果却不符合预期的场景后逐条积累的。你可以在自己团队里建立类似的故障档案每次排查完把原因补进去。5.3 后续扩展方向Hooks 与 Skills 的联动空间模板仓库做到这一步基本已经能覆盖日常开发里七八成的重复任务。再往后扩展我建议把触角伸到 Hooks 和 Skills 的联动上。Hooks 的价值在于硬性守门。比如我在一个涉及支付模块的项目里加了一个 PreToolUse Hook在模型执行Bash(git push)之前先扫描本次变更里是否包含密钥文件一旦命中立即拦截。这类检查如果只写在模板里属于软约束模型可能因为注意力漂移而忽略写在 Hook 里就是不管模型怎么想都必须执行的规则。Skills 则适合沉淀低频但复杂的专业能力。比如数据库索引审查、Kubernetes 配置校验、前端依赖安全审计这些任务每次执行都需要加载大量专业规则不适合塞进 Slash Command。把它们做成 SKILL.md 放在 .claude/skills/ 下模型会在匹配到相关任务时自动加载对应能力包比手动/command更自然。我目前的一个扩展方向是把项目里累积的线上故障案例做成一个 skill包含常见的故障模式、排查路径、应急处理脚本。这样下次再遇到相似问题时Claude Code 能被 skill 引导着更像一个经历过这类故障的老手而不是刚入行的实习生。从第一次把零散的 prompt 整理成模板仓库开始这个项目已经跟着我换过三个代码仓库迭代了十几轮。我现在最大的体会是模板真正管理的不是 AI而是团队协作的约定。把审查标准、设计规范、测试边界这些隐性知识写进模板等于让每个参与项目的人——无论是人还是 AI——都站在同一条起跑线上。未来这个仓库还会继续扩可能是更多专业领域的 skill也可能是和团队知识库打通让 AI 协作的边界再往前推一步。