我最早用AI写代码的时候，还是典型的“闲聊模式”：每开一个新对话，先把项目背景、技术栈、代码规范从头到尾粘贴一遍。一开始觉得没什么，后来项目一多就麻了——每个 session 里至少有十分之一的上下文浪费在重复交代上，而且写好一个 prompt 之后，下次换个人、换个目录又要全部重来。后来接触到 claude-code-templates 这类实践，说白了就是把“给 AI 的指令”从聊天记录变成项目里的持久化文件，让 Claude 一进场就知道这个项目的规矩、流程和红线。这篇文章就聊聊我搭建和沉淀这套模板的完整思路、配置细节，以及踩过的坑。适合正在用 Claude Code 写正经项目、想让个人产出更稳定、让团队协作更标准的开发者。
1. 为什么要做 claude-code-templates：先解决“没记忆”和“没流程”这两个问题
1.1 闲聊式编程的痛，比你想的更费钱
如果你只是拿 AI 写点一次性脚本，那聊胜于无的对话式交互完全够用。但只要是维护周期超过一个月的正经项目，闲聊模式的问题就会集中爆发。
首先是没有记忆。Claude Code 每次启动的上下文，可以理解为“一个新入职的员工”，你上次告诉过它什么，它记不住。我团队里有位同事，连续三天让 AI 写同一个模块的错误处理逻辑，每次都要重新说明“我们项目里错误码统一用 xxx 开头”“日志必须打 trace_id”。这些话说一遍不难，难的是每天都在说，而且每个人说的还不一样。
然后是没有流程。闲聊模式下的请求是原子化的：你让我改这个函数，我就改这个函数。但真实开发很少只有单步操作——改完代码要跑测试、要看 diff、要补文档、要过 lint，这些步骤如果每次都靠人肉提醒，AI 的产出质量就完全取决于你当时的心情和表达能力。
最后是不可复现。同一个需求，昨天那个 prompt 写得细，AI 输出就有模有样；今天这个 prompt 写得太糙，AI 就像第一天上班，满嘴跑火车。这不是 AI 不稳定，而是你的“输入”不稳定。
1.2 模板体系的三个层次：记忆、行为、流程
claude-code-templates 这个概念，我的理解不是简单放几个 markdown 文件就算完，而是要把人机协作沉淀成一套分层的资产。最实用的分层方式是这样的：
| 层次 | 载体 | 解决的问题 | 类比 |
|---|---|---|---|
| 记忆层 | CLAUDE.md、rules 目录 | 让 AI 知道项目是什么、规矩是什么 | 新人入职手册 |
| 行为层 | commands、agents | 让 AI 知道特定场景具体怎么做 | 岗位 SOP |
| 流程层 | workflows、hooks | 让多步骤操作按既定顺序执行 | 团队上线 checklist |
这三层缺一不可。只有记忆层，AI 什么都懂但不知道从哪下手；只有行为层，AI 知道怎么做但缺乏项目背景，容易按通用套路乱来；只有流程层，AI 会机械地走步骤，但每步的质量没人保障。
打个比方：你入职一家新公司，先看员工手册了解公司业务（记忆层），再看岗位说明了解每天干什么（行为层），最后跟着师傅走一遍从开发到上线的完整流程（流程层）。claude-code-templates 做的事情，就是把这三份文档写进项目里，让 AI 每次入职都自带培训。
1.3 什么样的团队/项目最需要这套东西
我自己的经验是，凡是“重复解释成本 > 配置模板成本”的场景，都值得做。具体来说：
- 团队项目：多人共用一套代码库，AI 产出风格却跟着操作者跑，review 成本极高。
- 长期维护项目：半年以上的项目，业务规则、目录约定、历史坑非常多，靠人脑记不现实。
- 有明确规范的场景：比如必须写单测、必须带 changelog、数据库变更要做迁移，这类操作完全适合模板化。
相反，如果只是临时脚本、一次性 demo、或者纯探索性质的原型代码，那没必要上模板，闲聊模式反而更灵活。别为了用模板而用模板，这是第一个要记住的原则。
2. 逐层拆解模板骨架：从 CLAUDE.md 到 hooks 的完整设计
2.1 记忆层：CLAUDE.md 的颗粒度怎么把控
CLAUDE.md 是 Claude Code 启动时自动加载的项目记忆文件，一般放在项目根目录，也可以用.claude/CLAUDE.md的方式做更细的划分。它解决的核心问题是：AI 每次启动都有“项目常识”。
写 CLAUDE.md 最容易犯的错，是把它当成一份大而全的文档来写，恨不得把需求文档、数据库表结构、接口文档全部塞进去。我最早就是这么干的，结果上下文直接被撑爆，真正的指令反而被淹没。正确的写法是只写“AI 必须知道但无法从代码里快速推断”的信息。
我的推荐结构是这样的：
- 项目一句话简介：这个项目做什么的，面向谁。
- 技术栈清单：语言、框架、关键库版本，注意不要写“我们用了 React”，而是写“我们用了 Next.js 14 + TypeScript，样式走 Tailwind”。
- 目录约定：哪个目录放业务代码、哪个目录放工具函数、新增页面要动哪些地方。
- 命令约定：启动命令、测试命令、lint 命令、构建命令，直接给可执行的。
- 已知的坑：比如“mock 数据只能放
__fixtures__，不要放src”“数据库迁移不允许回滚”。 - 编码规范里 AI 最容易违反的几条：错误处理方式、命名习惯、注释语言。
一个细节是：CLAUDE.md 也支持模块化拆分，用@导入其他文件。比如我在 monorepo 里就喜欢用：
@docs/claude/coding-standards.md @docs/claude/backend-conventions.md @docs/claude/frontend-conventions.md这样主文件保持精简，各业务域单独维护自己的规范，也方便不同团队各自更新。如果项目根目录的 CLAUDE.md 越来越大，说明你没有做好拆分，迟早会出问题。
另外提一句，Claude Code 有/init命令，可以自动生成一份初始化的 CLAUDE.md。生成结果可以作为起点，但千万别直接用——它基于代码猜测的信息只能算“大概齐”，你需要在里面加入业务背景、历史决策这些代码里看不出来的内容。
2.2 行为层：/ 命令的完整写法
行为层是 claude-code-templates 里使用频率最高的一层。Claude Code 支持自定义 slash command，本质上就是把你平时写在对话框里的那一大段 prompt 变成文件，放在.claude/commands/目录下，之后输入/review、/test、/commit就能直接触发。
一个命令文件大概长这样。以我最常用的代码审查命令为例：
--- description: 对当前分支的改动做一次完整代码审查 argument-hint: [可选] 指定审查重点，如 security、performance --- 你是一位拥有 10 年经验的资深代码审查者。请执行以下步骤： 1. 使用 git diff 获取当前分支相对主干的所有改动。 2. 仔细阅读每一处改动，重点关注： - 逻辑正确性：是否存在边界条件遗漏、空指针、竞态问题。 - 代码风格：是否符合项目约定（可参考 CLAUDE.md 中的规范）。 - 安全性：是否可能引入注入、越权、敏感信息泄漏。 3. 如果用户传入了审查重点（例如 security），请优先对该方向做深入检查。 4. 按以下格式输出审查结果： - 总体结论：通过 / 基本通过 / 需要修改 - 问题列表：每个问题标注【严重】【中等】【轻微】 - 建议修改方案：给出具体的修改思路，不要直接重写整段代码注意几个要点：
- frontmatter 里的 description 要短但准确，因为 slash command 列表里只显示这一行。
- argument-hint 是给调用者看的提示，说明这个命令接受什么参数。不写的话，AI 会认为这个命令不接收参数，导致你传参时它一脸茫然。
- 命令正文里要明确步骤和输出格式。模板的价值不在于让 AI 更聪明，而在于让 AI 的每次输出都稳定在一个可接受的水准。
类似的命令还可以有/commit（生成符合规范的提交信息）、/test（补单测）、/explain（解释某段代码逻辑）、/refactor（安全重构）。我的经验是，先做最常用的两三条，别一上来搞二十个，否则你记不住，AI 也容易被绕晕。
这里要特别提醒：命令文件里能写“必须”“禁止”这类强约束词，但别把约束写死到“每次都必须这样做”。因为真实开发场景千变万化，命令模板应该给“轨道的指引”，而不是给“标准答案的脚本”。
2.3 角色层：agents 把专家装进独立上下文
如果说 slash command 是“一个任务模板”，那 agents 就是“一个虚拟角色模板”，适合固定领域、重复出现的子任务。Claude Code 支持 subagents，把角色文件放在.claude/agents/目录下，AI 在主流程里遇到对应任务时，可以主动把这个角色拉出来干活。
举个例子，我在后端项目里放了一个数据库迁移审查员角色。文件大概是这个思路：
--- name: db-migration-reviewer description: 专门审查数据库迁移脚本，检查是否存在破坏性变更 --- 你是一名数据库迁移审查专家。当分支中存在数据库迁移脚本时，你需要： 1. 检查迁移脚本是否包含破坏性操作（DROP COLUMN、ALTER TYPE 等）。 2. 检查迁移是否配套了回滚方案，没有回滚方案的迁移标记为【严重】问题。 3. 检查新索引是否可能影响线上大表写入性能，给出缓释建议。agents 和 command 的核心区别在于上下文隔离。命令是在主上下文里执行的，模板写得再长也会占用主线上下文；而 subagent 是在独立上下文里跑任务的，出结果之后只把结论带回主流程，不会把中间过程全部塞进主线。所以对于那些“步骤多、中间产物大”的任务，比如日志分析、跨文件重构、批量文档生成，用 agents 能明显缓解上下文压力。
但 subagent 也有代价：它看不到主会话的完整对话记录，只能拿到你喂给它的背景信息。所以设计 agent 时，一定要在 description 里写清楚前置条件，或者在调用时把必要的背景一并传给它。
2.4 流程层：workflows 和 hooks 把步骤钉死在执行路径上
最容易被忽略的是流程层。很多团队有 CLAUDE.md、有命令模板，但 AI 依然产出混乱，原因在于多步骤的动作没有编排。比如一次提测流程里要跑 lint、单测、构建、生成 changelog，如果这些步骤完全靠 AI 自己临场发挥，它很可能跳步骤、乱顺序。
workflows 的概念可以理解为一套有顺序的模板组合。它本质上是在 AI 调用工具前，就告诉它“这条路必须按这个顺序走”。如果你不是特别在意语法细节，最简单的方式是直接在命令正文里把步骤编排好，告知 AI 必须逐步执行，并设置“前置检查点”。我从实践里学到的经验是，流程模板的关键不在于把每一步写得多细，而在于把“检查点”插对位置。
hooks 则是更底层的守护机制。Claude Code 有一系列 hook 事件，比如PreToolUse在 AI 正要调用工具前触发，PostToolUse在调用完成后触发，Stop在一次响应结束时触发。它们就像是工程里的“门禁”，可以防止 AI 做出危险动作。
举个例子，我担心 AI 在重构时误删迁移文件，就在 CLAUDE.md 里配置了一个PreToolUsehook，检查 Bash 命令里是否含有rm db/migrations/这类危险操作，有的话直接拦截，返回提示信息让 AI 重新决策。大致思路是：
[hooks] PreToolUse = [ { matcher = "Bash", hooks = [{ type = "command", command = "python .claude/hooks/guard.py" }] } ]hooks 脚本的写法完全看你的需求，本质是拿到即将执行的命令，做一层校验。这样即使 AI 本身不够谨慎，流程层也能兜底。hooks 该不该写进模板？我的回答是，凡是你不希望 AI 脑抽来一刀的操作，都有必要。比如不删数据库目录、不改锁文件、推送前强制跑测试，这些都可以用 hook 半自动卡住。
不过也别过度设计。我见过有人给 AI 套了十来个 hook，结果改一行代码要触发四五次检查，响应速度肉眼可见地变慢，最后开发者自己都嫌烦，把 hook 全禁了。门禁要设在最关键的几个节点，大量琐碎操作应该交给命令模板里的步骤约束就够了。
3. 一套可直接落地的模板组合方案：目录规划、PR 审查与发版检查
3.1 从一个干净的目录结构开始
搭建 claude-code-templates 的第一步，是规划好.claude目录。以我现在维护的一个中型 Web 项目为例，目录长这样：
.claude/ ├── CLAUDE.md ├── commands/ │ ├── review.md │ ├── commit.md │ ├── test.md │ └── explain.md ├── agents/ │ ├── db-migration-reviewer.md │ └── security-reviewer.md ├── hooks/ │ ├── guard.py │ └── check_sensitive_file.py └── rules/ └── coding-standards.md这份结构很朴素，但足够用。我把 CLAUDE.md 放在根目录，因为它是每次启动必加载的东西，越显眼越好；commands 和 agents 按功能拆分；hooks 脚本单独抽出来，因为里面有实际可执行的代码，需要独立测试和 review。
有些团队还会在项目根目录放一份CLAUDE.local.md之类的个人记忆文件，用来存个人偏好。我的建议是，团队共用的内容放.claude/并提交到 git，个人习惯放全局目录，不要混在一起，否则很容易出现“我的模板被同事改动后我不适应”的尴尬局面。
3.2 从零搭一个 PR 审查模板
PR 审查是我认为最值得先做模板的场景，因为它触发频率高、标准相对固定、而且输出的质量直接关系团队代码质量。上文已经给了一个精简版，这里说几个我当时搭建时反复调整的细节。
第一，审查范围必须明确。如果没告诉 AI “只看当前分支相对主干的改动”，它很容易从头到尾把整个项目“review”一遍，生成一堆无关痛痒的废话。所以模板第一步永远是git diff，而且是限定范围的 diff。
第二，输出格式要结构化。我踩过的坑是早期让 AI “自由描述问题”，结果它每次输出的风格都不一样，有时是长段落，有时是表格，review 效率很低。后来在模板里强制输出“总体结论 + 问题列表 + 建议方案”，格式固定之后，团队同学扫一眼就能定位问题。
第三，允许传入审查重点。我团队里有人希望重点关注安全，有人希望重点关注性能，如果模板写死“全面审查”，那么每次都会四平八稳，没有针对性。通过argument-hint开放参数后，/review security就会优先深挖安全方向。这个灵活性很重要。
实际使用中的效果是：以前人工 review 一个 PR 可能需要 15 分钟快速浏览，现在 AI 先出一版结构化报告，人工只需要验证 AI 指出的问题是否真实存在、以及有没有漏掉方向性问题。整体 review 时间大约能压缩一半以上。
3.3 设计“提测/发版”检查工作流的思路
发版检查比 PR 审查更强调顺序。我遇到过一个很经典的翻车现场：AI 在帮我整理发版说明时，发现测试还没跑完，就先把 changelog 写好了；后来测试果然挂了，changelog 白写。这不是 AI 蠢，是我没在模板里给它一套顺序约束。
设计发版检查工作流时，我把步骤拆成了这样一张表：
| 步骤 | 动作 | 判断标准 | 失败处理 |
|---|---|---|---|
| 1 | 运行 lint | 无 error | 修复后重跑 |
| 2 | 运行单测 | 全量通过 | 定位失败用例，修复后重跑 |
| 3 | 构建产物 | 构建成功 | 查看报错，修复后重跑 |
| 4 | 对比主干 diff | 确认变更范围 | 无 |
| 5 | 生成 changelog | 按约定格式 | 缺失信息则标注待补充 |
| 6 | 标记提测说明 | 输出完整报告 | 无 |
然后把这个顺序写进一个发版命令模板里，并在开头明确写一句“在完成上一步并确认结果之前，禁止跳到下一步”。这句话看着简单，实际是流程模板的灵魂。你不写出来，AI 就默认可以把任务拆成任意顺序并行推进；你写出来，它就会按部就班地走。
如果你希望更硬性的保障，可以在 hooks 层面加一道“运行测试前先检查 lint 是否通过”之类的守卫。但我觉得对大多数团队来说，模板里写清楚顺序已经够了，hooks 更适合用来防那些不可逆的危险操作。
3.4 模板放进团队仓库后的协作维护
模板不是写一次就一劳永逸的，它跟代码一样需要迭代。我目前的做法是：
.claude/目录提交到项目 git 仓库，所有改动走 PR 流程，跟代码一样被 review。- 模板变更时，在 PR 描述里说明“这个改动会影响哪些 AI 行为”，方便同事理解。
- 每月抽一次时间，看哪些命令的调用频率最低，低于阈值就考虑删掉或者改掉。没人用的模板就是死代码，留着只会让 AI 加载更多无关的指令。
另外，我强烈建议把“AI 行为规则”和“业务代码规范”放在一起维护。很多团队规则文档散落在 wiki 里，AI 根本看不到；与其花力气让 AI 去读 wiki，不如把最关键的几条直接摘进CLAUDE.md。记住一个原则：AI 只能遵守它看得见的规则，看不见的规则等于不存在。
4. 模板实战避坑：常见问题与排查技巧实录
4.1 模板没生效？先查加载链路
我身边十个用 Claude Code 的人，至少有三四个遇到过“我明明写了命令文件，但 AI 不认”的情况。排查顺序基本是固定的：
- 文件位置对不对。命令必须在
.claude/commands/下，agent 必须在.claude/agents/下，放错目录就加载不到。 - 文件后缀对不对。虽然 Claude 能读很多格式，但最稳的还是
.md，别用.txt凑合。 - frontmatter 格式对不对。
---之间的键值对如果写错，整个文件可能被当成普通文档，而不是命令定义。 - 改完重启会话没有。Claude Code 在会话启动时读取模板文件，运行中的会话里改了文件，通常不会立即生效。遇到“我改了但没用”，先重启再说。
我自己的一个真实教训是：某次把description写成了desciption，拼写错误，命令倒是能触发，但命令列表里那行说明显示不出来，同事还以为是系统 bug。后来用了一段时间才发现是拼写问题。所以模板文件也要定期 review，别觉得写完了就没事。
4.2 上下文还是不够用？问题往往出在模板太长
加了模板之后，AI 的上下文占用不降反升，这种情况我也遇到过。典型原因是：CLAUDE.md写了一万多字，每条命令模板也动辄好几千字，AI 每次启动或触发命令时，这些内容全部被加载，挤占了本应留给代码分析的上下文空间。
解决办法有三个方向：
- 精简记忆层：
CLAUDE.md只保留高频信息和项目红线，低频细节放到rules/子文件里，用@导入，需要时再加载。 - 命令模板走“短指令 + 外部文档”模式：正文只写步骤骨架和输出格式，详细规则写成单独文档，在命令里让 AI 先读文档再执行。
- 能用 subagent 的任务尽量用 subagent：subagent 的指导文件只占主上下文极小一部分，执行过程的中间产物不会回流到主线，能有效缓解主上下文压力。
我见过有些团队把命令模板写得比需求文档还长，结果 AI 每次执行任务前光是读完自己的“说明书”都要花不少时间，响应慢而且理解反而变差。模板不是越长越好，是越准越好。
4.3 模板让 AI 变蠢了？检查约束是否过度
有一种失败模式是：模板写得非常详细，AI 反而表现得像被格式捆住手脚，失去了灵活性。举一个具体案例，我在模板里写过“所有函数都必须带类型注解、所有错误必须用 Result 返回、所有日志必须带 trace_id”，结果 AI 在改一个简单工具脚本时也强行套这套规则，把一个 10 行的脚本写成了 80 行样板代码。
问题的根源在于，我把“团队核心业务代码的规范”错误地应用到了“所有代码”上。修正方式是给模板加适用范围限定，比如明确写“仅在修改src/下的业务代码时执行上述规范，工具脚本和测试代码可按实际需要简化”。约束要给方向，但也要留出口。
还有一个常见的过度约束是把命令里的每个措辞都写得咄咄逼人，满屏“必须”“绝不能”“否则后果严重”。AI 确实会遵守，但它会变得畏手畏脚，遇到稍微模糊一点的场景就不敢动手，非要反复跟你确认。我的体会是：模板的语气要像“靠谱的资深同事给你交代工作”，而不是“安全员在宣读违规处罚条例”。
4.4 安全与维护：模板也会埋雷
最后说说安全。很多人以为模板就是个 prompt，不会有风险，其实不然。hooks 里执行的是真实命令，如果 AI 或攻击者通过某种方式修改了 hooks 脚本，那危险性跟篡改构建脚本是一模一样的。所以：
- hooks 脚本一定要放在 git 里做版本管理，改动走 review。
- 不要把密钥、token、数据库口令写进任何模板文件，AI 随时可能把模板内容展示给正在看日志的同事。
CLAUDE.md里如果写了“不要上传某某文件到服务器”，那也只是约束 AI 的软规则；真要防文件泄漏，还得在 hooks 或代码层面做硬拦截。
维护方面，我给自己的硬性要求是：每季度过一遍模板清单。打开.claude/commands/目录，挨个试一下还能不能跑，描述是否准确，步骤是否还符合当前项目的流程。项目改版了，代码规范变了，团队流程变了，模板没跟着变，它就从“资产”变成了“负债”。
另外一个小技巧：给团队里所有人都开放模板的编辑权限之前，先指定一个“模板 owner”。否则今天你加一条规则、明天他改一条规则，一个月后模板里充满了互相矛盾的内容，AI 的行为会变得非常奇怪。owner 不需要是领导，但一定要是有全局视角、能被大家信任的人。
我自己在实操中最深的体会是：claude-code-templates 的价值不在于把模板堆得又多又全，而在于把团队真正高频、重复、标准化的那部分工作流程固化下来。早期的我总想着一口气把所有东西都模板化，结果维护模板的时间比省下来的时间还多；后来收敛到几条核心命令、一份精简的 CLAUDE.md、两三个 agent 之后，收益才真正开始显现。如果你也想搭这套东西，先别急着规划宏大蓝图，挑一个你每周至少会做三次、且每次都要向 AI 反复解释背景的操作，把它做成第一个模板。用起来了，再加下一个，这条路比一上来就想搞全套要稳得多。
