前阵子我一直在用 Claude Code 处理代码评审、依赖升级、日志排障这几类高频活儿。一开始效率确实高，但用着用着发现一个尴尬的问题：每次对话都要把项目背景、约束条件、输出格式重新描述一遍，像极了刚换同事就要重新交代一遍项目背景的日子。后来我把这些重复的提示词和工作流固化成了 claude-code-templates——一套可复用的模板体系，才真正把 AI 编程这件事从“一次性问答”变成了“可积累的资产”。
这篇文章会把我搭建这套模板体系的核心思路、目录设计、关键字段、hooks 配置，以及实测踩过的坑完整分享出来。适合正在用 Claude Code、或者打算把自己的 AI 编码流程标准化的人，我会尽量把每个环节的“为什么这么做”也讲清楚。
1. 模板到底由什么构成：先搞清楚这五个积木块
很多人一提“模板”就以为只是把提示词存成一个文件。其实在 Claude Code 里，模板体系至少由五块积木组成，它们各有分工，配合起来才是一套完整的可复用方案。我在早期只用了其中的斜杠命令，后来才慢慢补齐其他部分。
1.1 项目记忆文件：CLAUDE.md 解决“来了就懂”的问题
CLAUDE.md 是放在项目根目录下的记忆文件。它的作用相当于给 AI 做“入职培训”：告诉它这个项目是什么架构、有哪些约定、测试怎么跑、哪些目录是生成的不许乱动。
一开始我总觉得这就是个 README 的变体，没必要太认真。直到有一次让 Claude Code 改一个老项目，它自作主张改了数据库迁移脚本的目录结构，我才意识到，AI 没有项目记忆的时候，所有决策都靠猜。把关键约束写进 CLAUDE.md，不是可选项，而是必选项。
我在写 CLAUDE.md 的时候会按区块组织：项目概述、技术栈、目录约定、常用命令、禁止事项。每个区块控制在五条以内，写多了 AI 反而抓不住重点，也会占用上下文空间。
1.2 斜杠命令：把你的最佳实践做成可复用指令
斜杠命令（Slash Commands）是 Claude Code 支持的一种自定义指令，存放在.claude/commands/目录下，每个文件就是一个 Markdown 格式的提示词模板。调用时用/命令名就能触发。
这应该是模板体系里最直观的部分。比如我写了一个/upgrade-deps命令，里面规定：先扫描依赖清单，再逐个检查新版本和 changelog，最后输出一份变更风险报告。用的时候只需要敲一下命令，再也不用重复描述这一整套流程。
斜杠命令的强大之处在于它支持占位参数。你可以在命令里写{{依赖名}}、{{目标版本}}这类变量，执行时 AI 会向你询问具体值。这让同一份模板可以应对不同任务，而不是为每个场景单独建一个文件。
1.3 hooks：在 AI 看不到的地方设一道自动化闸门
hooks 是 Claude Code 的事件钩子，可以在 AI 执行工具调用前后插入一段外部脚本。比如在它执行 Bash 命令之前，先检查当前分支是否在保护名单里；在它读取文件之后，记录这一次读写了哪些文件。
我最早理解不了 hooks 和模板有什么关系，后来才发现，hooks 是模板的“守门员”。模板告诉 AI 该怎么做，hooks 保证 AI 没有越界。两者配合，才称得上是一个完整的自动化工作流。
举个实际例子：我有一个模板是自动生成 API 接口文档。如果没有 hooks，AI 可能会直接把内部接口的完整响应体贴进文档（我踩过这个坑，差点把内网地址发出去）。后来我在 PreToolUse 阶段加了一个脚本检查，凡是输出路径匹配到公开文档目录时，就额外跑一次敏感信息扫描。这样模板负责效率，hooks 负责安全。
1.4 子代理与全局配置：更细的分工和更稳的默认值
子代理（Subagents）可以理解为“拥有专属系统提示词的 AI 分身”。比如我定义了一个专门的 CodeReviewer 子代理，它的提示词里强制要求从可维护性、性能、安全隐患三个维度提意见，和主对话里的通用评审风格完全不同。
全局配置（settings.json）则决定了模板执行时的默认行为，比如默认模型、是否允许自动执行命令、输出的 verbose 程度。我把这些统一收敛到配置文件里，模板文件本身就能保持干净，只负责业务流程，不掺杂运行环境的杂音。
这五块积木的关系，我用一句话概括：CLAUDE.md 提供背景，斜杠命令定义流程，subagents 分配专业角色，settings 决定运行环境，hooks 卡住安全边界。下面我分别展开讲怎么搭。
2. 别急着造模板：从真实工作流里提炼，先有过程再有成品
我见过不少同事一上来就对着空白文件憋模板，写了半天发现根本不好用。原因很简单：还没跑过几次真实任务，你根本不知道哪些步骤是稳定可复用的，哪些只是这次碰巧需要的。我的做法是先把同一个类型的活干上两三次，每次记下操作步骤，然后从对话记录里提炼骨架。
2.1 一个真实场景：老仓库的依赖升级
举一个我常遇到的场景：给一个维护了两年多的后端仓库做依赖升级。这个仓库用的是 Go，依赖倒是不算多，但有几个库的版本跨了主版本号，升级意味着可能要处理破坏性变更。
第一次做这个任务，我把一大段需求描述敲进了 Claude Code：项目背景、要升哪些包、注意兼容性、最后要出报告。整个过程大约花了四十分钟，AI 一边看 go.mod 一边查 changelog，中途还因为找不到某个包的发布说明卡住了。任务完成之后我复盘发现，这次对话里有大量信息其实是可以预先固化的，比如：
- 这个项目的测试命令是什么
- 哪些包属于核心业务依赖，升级需要谨慎
- 输出报告需要包含哪些字段
这些信息第二次、第三次做同类任务时，我还得重新描述一遍。那一刻我就决定要把这套流程沉淀成模板。
2.2 从对话里抽取可复用骨架
抽骨架的时候，我不会去看 AI 的具体回复，只看我给它的指令和我补充的修正。把这些整理下来，就是模板的雏形。对于依赖升级这件事，骨架大概是六步：
- 读取依赖清单文件，列出当前版本与最新版本
- 筛选出有主版本变更的依赖，逐个查看上游 changelog
- 对每个依赖判断破坏性变更风险等级
- 制定升级顺序，先低风险后高风险
- 执行升级并跑完整的测试套件
- 输出一份包含变更内容、风险等级、测试结果的报告
这六步并不复杂，但它是从真实操作中提炼出来的，比凭空想象的流程靠谱得多。因为我知道第一步必须让 AI 先看清依赖全景，不然它很容易陷进某个包的分析里出不来。
把骨架写成斜杠命令之后，第二次执行同样的任务，我只需要敲/upgrade-deps，再把目标依赖列表交给它。时间从四十分钟压缩到了十五分钟左右，而且输出报告的格式稳定了，不再需要我每次在对话里重复“报告要有表格、要标注风险等级”这类话。
2.3 第二类模板：新项目初始化里的标准动作
依赖升级是从重复劳动里提炼模板的典型例子，另一类是“从零开始的标准动作”。比如我用 Claude Code 初始化一个新项目的时候，每次都要做这些事：确认技术栈、生成目录结构、搭好 lint 和格式化配置、初始化 Git、写第一版 README。
这些动作的规律性比依赖升级更强，因为主观判断的成分更少。我把它们固化成/scaffold-project模板，执行时只需要填项目名称和技术栈两个参数。
做完这两类模板之后我总结出一个原则：不需要一开始就追求模板覆盖所有场景，先挑你自己每周都会做至少一次的任务。原因是，频率越高，模板带来的收益越大，而且你会更频繁地发现模板的缺陷，迭代速度也会更快。
3. 模板库的目录结构与命名哲学
模板攒多了以后，最大的问题不是没有模板，而是找不到该用哪个。我的模板库一度堆了三十多个命令文件，最后调用频率反而下降了，因为每次都要翻目录。后来我花了一个下午重新整理了目录结构和命名规则，情况才有了本质改善。
3.1 我的目录长什么样
我采用的目录结构是区分“项目级模板”和“全局模板”的。项目级模板放在各个仓库的.claude/commands/下，全局模板放在用户目录的~/.claude/commands/下。前者服务特定项目的业务逻辑，后者是人人都能用的通用操作。
~/.claude/ ├── CLAUDE.md ├── settings.json └── commands/ ├── 01-code-review.md ├── 02-upgrade-deps.md ├── 03-scaffold-project.md ├── 04-log-analysis.md ├── 05-api-doc-gen.md └── 06-bug-triager.md每个命令文件都用了两位数字前缀来固定排序，这样在自动补全列表里看到的就是一个稳定的顺序，而不是随机位置。项目级命令我通常会加-local后缀来区分，比如01-db-migration-local.md，避免和全局命令混淆。
3.2 命名规则：动词优先，输出统一
我给命令命名的规则是“动词优先”：upgrade-deps、code-review、log-analysis、scaffold-project。这样一眼就能看出这个命令是做什么动作的。
命名时还有一个容易被忽略的细节——同一个动作的模板，输出格式要保持一致。比如所有跟代码审查相关的模板，无论审查对象是 Go 还是 Python，最终都要输出“问题列表 + 严重级别 + 修改建议”的三段式结构。这样我从一个项目切到另一个项目，看到输出格式的熟悉感还在。
另外，我规定每个模板文件必须在 YAML 头里写清楚描述（description）和参数提示（argument-hint）。这两个字段虽然不参与 AI 的实际推理，但在命令列表展示时，能让使用者（包括未来的自己）快速明白这个模板是干嘛的、需要什么参数。
3.3 模板粒度：小而美优于大而全
目录整理完之后，我又踩了一个新坑：试图把“代码审查 + 依赖升级 + 测试修复”三个流程塞进一个模板里，结果模板变成了一篇三千字的巨型指令，AI 反而不知道该先干哪件事。
后来我把模板粒度定成“一个模板只完成一件事”。如果一件事内部有多个阶段，就拆成多个模板，用命名序号串联。比如我做“依赖升级并修复测试”的完整流程，实际会依次调用/upgrade-deps和/fix-tests两个模板，而不是把它们合并。
这样做的好处是每个模板的指令长度短、上下文开销小、出错时定位也容易。组合使用带来的灵活性，远远超过一个巨型模板能带来的所谓“一步到位”。
4. 一份模板的关键字段：从 YAML 头到验收清单
一个真正好用的模板文件，远比“一大段提示词”复杂。我翻了几个公开项目里的 Claude Code 模板，加上自己迭代了十几版，总结出一个相对稳定的字段结构。下面就用一个完整的模板示例来讲。
4.1 YAML 头字段：让模板自带元信息
每个斜杠命令文件的开头都有一段 YAML front matter，提供命令的元信息。我的模板通常包含四个字段：
--- description: 对存量仓库执行依赖升级，输出风险评估报告 argument-hint: 可选，传入目标依赖列表，多个依赖用逗号分隔 allowed-tools: Read, Grep, Glob, Bash ---description是必填的，它会显示在/help列表里。argument-hint提示调用时可传什么参数。allowed-tools限制了这个模板执行时可以调用的工具，我一般只放开必要的读写、搜索和执行命令的权限，不用的工具一律不给，减少 AI 做出意外行为的可能。
4.2 上下文采集区：只让 AI 读它该读的东西
模板正文的第一段我固定命名为“上下文采集区”。这一段的目的是让 AI 在执行真正工作之前，先基于固定路径读取一组文件，形成对任务的准确理解。
开始之前，请按顺序完成以下信息的收集： 1. 读取当前目录下 go.mod（若不存在，请输出“未找到依赖清单”并停止） 2. 提取所有 direct dependencies 的名称和当前版本 3. 运行 `go list -m -u all` 获取可用的最新版本列表 4. 汇总每个依赖的名称、当前版本、最新版本、是否跨主版本号这段指令最大的价值是它把“先收集信息再动手”固化成硬规则。如果没有这段，AI 经常会跳过第一步，直接凭印象开始改代码——它并不知道哪个依赖需要升级。
我在上下文采集区还有个隐藏设计：每一步都要求 AI 输出一个明确的中继结果（比如“已读取依赖清单，共找到 42 个直接依赖”）。这样一旦任务卡住，我能从输出里立刻定位是采集环节出错了，而不是后面分析环节的问题。
4.3 约束区：把“不要做”写清楚，比“要做”更重要
模板里最容易被忽略的是约束区。因为在写模板的时候，你满脑子都是“要让它做什么”，很少会花心思去想“不应该让它做什么”。但实践下来，约束区写得好不好，直接决定了模板的上限。
执行过程中，必须遵守以下约束： 1. 不得修改 go.mod 和 go.sum 之外的任何文件 2. 破坏性变更（breaking change）必须单独标记，不得混入常规升级 3. 升级顺序必须从风险最低的依赖开始 4. 任何依赖升级后，必须运行 `go test ./...` 验证 5. 如果某个依赖的最新版本不明确，优先查询上游官方 changelog，禁止猜测这些约束来自我在真实项目里翻过的车。第一条是因为有次 AI 顺手把源代码文件的 import 也改了。第二条是因为报告里普通升级和破坏性变更混在一起，导致测试环境升级时出了事故。写下来之后，模板的稳定性和可预测性有了质的提升。
4.4 验收清单：定义“做完”的最小标准
模板的最后一段，我会写验收清单。这大概是和普通提示词区别最大的一点：普通提示词说“输出报告”就完了，我的模板会明确写出“什么样的报告才算合格”。
完成后，请输出一份 Markdown 报告，包含以下章节： 1. 升级总览：一个表格，包含依赖名、当前版本、目标版本、风险等级 2. 破坏性变更明细：列出所有跨主版本号的依赖，附 changelog 关键摘要 3. 测试结论：记录每次升级后 `go test ./...` 的输出摘要，失败必须贴出完整错误 4. 遗留事项：列出需要人工确认但未自动处理的问题 报告输出前，请对照以上章节逐项自检，缺失任何一项都需要补全后再输出。验收清单的存在，给“做完”下了一个可操作的定义。没有它，AI 往往会觉得自己写的三段话已经足够好了。这个细节帮助我在大多数场景里拿到结构一致、可直接贴进文档的产出物。
5. hooks 与临时规则：让模板在更多场景自动生效
模板本身解决的是“主动调用”的问题。但有些时候，你希望在特定事件发生时自动触发某个流程，而不是每次都在对话框里敲命令。这时候 hooks 和临时规则就派上用场了。
5.1 hooks 配置：文件变更自动触发校验
我在.claude/settings.json里配置了一个简单的 hooks 脚本。它做的事情是：每当 AI 准备执行 Bash 命令的时候，先检查当前 Git 分支名里是否包含release/前缀。如果是，就拒绝自动执行高风险的写操作。
{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "node scripts/check-protected-branch.js" } ] } ] } }配合模板使用时，这套自动机制的好处很明显。比如/upgrade-deps模板允许 AI 执行go get这类写操作，但如果在release/分支上，这条命令会被 hook 拦截并提示你确认。有了这层保障，模板可以更大胆地授权，因为越界动作会被外部脚本卡住。
5.2 临时置顶规则：让同一份模板适配不同分支
项目之间的差异，不应该靠复制模板来解决。我常用的一种做法是在对话开头用置顶指令临时补充项目上下文，而模板本身保持通用。
比如01-code-review.md是全局通用模板，我在某个仓库里执行时，会在对话开头追加一句：
本次审查请额外关注该项目的多租户数据隔离逻辑，相关文件位于 internal/tenant/，审查时必须以安全为最优先级。CLAUDE.md 已经写了通用约束，模板定义了标准流程，临时置顶规则负责“这一次的特殊要求”。三者叠加而不互相覆盖，这是我从多次踩坑里试出来的协作方式。如果你发现某个项目的特殊要求反复出现，那就应该把它从置顶规则升级为项目级 CLAUDE.md 或项目专用模板，减少每次的临时输入。
5.3 组合示例：一次完整的“升级+自检+收尾”
把模板和 hooks 配合起来的完整链路，我通常这样组织：先手动触发/upgrade-deps，AI 按模板采集上下文、制定升级计划；然后逐个执行依赖更新，每次go get都经过 PreToolUse 钩子校验分支；升级完成后，模板会要求运行全量测试；最后输出报告。
如果中间有任何一步测试失败，AI 会基于失败信息尝试修复，但修复行为的工具权限在 hooks 里被限制为只能修改源码文件和测试文件，不能动 CI 配置。这样既给了 AI 自主修复的空间，又守住了不该碰的边界。
从这个链路可以看到，模板负责定义业务流程，hooks 负责在关键节点插桩控制。前者是你的“工作方法”，后者是你的“安全制度”，缺一不可。
6. 多个模板的版本管理与团队分发
模板数量一旦超过十几个，版本管理就成了新问题。团队协作时更是如此：你改了模板，同事的本地还是旧版，两边跑出来的结果对不上，排查起来非常痛苦。这一节我分享目前用下来比较顺手的维护方式。
6.1 个人模板库怎么用 Git 维护
我把自己所有的模板放在一个单独的 Git 仓库里，全局命令软链接到~/.claude/commands/。目录结构按类别组织，本地上传后每次改动都有记录，回滚也很方便。
# 初始化模板仓库 mkdir -p ~/claude-templates/commands cd ~/claude-templates git init # 建立软链接（macOS / Linux） ln -s ~/claude-templates/commands ~/.claude/commands每次改模板，我会更新文件头部的last-updated字段，然后在 commit 信息里写清楚这次改了什么、为什么改。比如“将报告要求从中文改为中英双语，因为合作方需要英文版”。这种记录很重要，因为模板的演变本身就是你工作流演变的日志，复盘时价值极高。
6.2 团队分发：怎么避免互相踩踏
团队场景下，我建议把模板仓库作为基础，再为每个项目单独建一个“项目模板仓库”或目录。个人通用的放在~/.claude/commands/，项目专用的放在项目仓库的.claude/commands/，用 Git 正常管理。这样既能共享通用模板，又能保留项目特化内容。
分发时要注意的另一个点是全局变量的使用。尽量不要在模板里写死文件路径，除非它真的是全局唯一的。如果模板需要引用项目内路径，优先让 AI 在执行时通过扫描来确定，或者通过参数传入。这样一份模板在所有项目里都能用，而不是只能在一台机器、一个仓库里跑。
6.3 更新节奏：每两周至少清理一次垃圾
最后一条经验是定期清理。模板文档和代码一样，也存在“腐化”问题。我给自己定的节奏是每两周检查一次模板使用频率，连续两周没被调用过并且没有计划要用的模板，就移入archive/目录。保留太多低质量模板，不仅让/help列表变得冗长，而且会误导自己在关键时刻选错模板。
清理的时候还要看模板里是否有过时的步骤。依赖升级模板里的测试命令，如果项目已经换过测试框架却没同步更新，那这个模板执行起来就会当场报错。定期对照真实项目跑一遍核心模板，比一年到头囤模板然后只在演示的时候用，要有用得多。
7. 实测翻车记录：这些坑我踩过了，你直接绕开
最后这部分是我最想写的，因为网上的模板教程大多只展示“正确做法”，很少聊失败案例。我是在不断翻车的过程中才把模板体系调整成现在的样子。下面的几个坑，每一条都真实发生过。
7.1 过拟合：模板写太死，任务直接干崩
我最早写过一个代码生成模板，为了追求“严格”，把输出格式规定得非常死：每个函数必须带三行注释、每个结构体必须带 tag、错误处理必须拢进统一函数。结果执行起来特别僵，遇到边界场景 AI 会不断地试图套模板，反而忽略了任务本身。
调整思路是放松非核心约束。现在我会把要求分成两类，一类是硬约束（必须在验收清单里体现），一类是软建议（模板里写明“如果会影响代码可读性，可以偏离”）。硬约束保证质量底线，软建议保留灵活性。这个度需要反复试，没有捷径。
7.2 上下文采集过载：钱没少花，活没干对
有段时间我沉迷于让模板“尽量多读文件”，觉得信息越足 AI 判断越准。结果上下文占用飙升，执行速度变慢，而且因为无关信息太多，AI 反而把重点搞偏了。
后来我给每个模板立了个规矩：上下文采集区里明确只读必要文件，并且限制最多扫描的条目数。比如依赖升级场景只读 go.mod、go.sum 和上游 changelog，不读源代码实现。如果 AI 在分析过程中确实需要看某个包的实现，它可以在执行计划里主动申请，而不是一开始就一股脑全读进来。
7.3 指令冲突：CLAUDE.md、全局命令、hooks 互相打架
模板体系越来越复杂之后，我遇到过一种诡异的故障：CLAUDE.md 里说测试要用yarn test，项目级模板里写的是npm test，全局 hooks 又在文件变更后自动跑了一次 lint。结果 AI 在执行同一个任务时收到互相矛盾的指令，先后跑了三套测试命令，浪费了大量时间。
排查之后我定了一个优先级原则：项目级 CLAUDE.md 高于全局 CLAUDE.md，项目专用模板高于通用模板，hooks 只做安全拦截不做业务决策。并且在模板里明确写一句“若与项目级 CLAUDE.md 冲突，以项目级配置为准”。从此这类问题基本绝迹。
7.4 模板垃圾化：只增不删的必然结果
最后一个坑是“垃圾模板”。我从最初的几个模板积累到三十多个之后，发现真正高频使用的始终只有五六个，剩下的大多是某个项目一次性场景产出的半成品。它们躺在命令列表里，偶尔还会被误调用，产生一些莫名其妙的输出。
现在我的处理原则是：一个模板必须被连续使用三次以上，才从临时脚本转正为正式模板；超过两周没用的模板一律归档。归档不是删除，等哪天真的需要，再拉出来改改也来得及。这种“先转正后入库”的机制，可以避免模板库被一次性需求污染。
我自己现在的使用习惯是，每次完成一个比较复杂的任务，都会在对话最后让 Claude Code 基于这次对话生成一份模板初稿，然后我再手动审查一遍，把项目特化的部分剥离，只保留可复用的流程骨架。这样积累的速度远比凭空设计快得多，而且每份模板背后都有一个真实跑通过的任务案例支撑。希望你搭模板的时候也能用上这套思路，少走些弯路。
