如果你已经用 Claude Code 写过一段时间真实项目大概率体验过这种精神分裂同一个工具状态好的时候能给你设计出完整的数据表并写好迁移脚本状态差的时候连“删除这行代码会影响哪个模块”都说不清楚。我在连续切换三个项目之后最大的感受是Claude Code 的能力其实一直在线掉线的只是“上下文”。claude-code-templates 就是我用来解决这个问题的一套方法论——把技术栈、代码规范、工作流程、角色分工这些“恒定信息”从对话里抽出来固化成模板文件让每次会话启动时就自动加载。这篇文章会从痛点讲起给出完整的模板库搭建方案三层 CLAUDE.md、斜杠命令、子代理、Hooks以及团队共享的落地细节。刚接触 Claude Code 的人可以照着搭已经在用的人也能从里面捡到一两个值得抄的配置。1. 没有模板时的真实痛点每次对话都在重建上下文1.1 你与 Claude Code 的“双输”体验先说个我自己反复经历的场景。周一上午启动一个新项目我在终端里用 Claude Code 写一个 Go 服务第一轮对话我会叮嘱它“用整洁架构、不要用 ORM、错误处理用 error wrapping、日志统一走 slog。”它第一版代码写得有模有样。到了下午切回上周的电商后台项目我又得重新交代一次 React 组件规范第二天回到 Go 项目它写了一会儿竟然又开始往 struct 上怼 gorm tag——因为那次会话我没提“不要用 ORM”它把默认行为释放了出来。这种“双输”体现在两个地方。从我的角度看每天真正写业务逻辑的时间被大量重复的“背景说明”吃掉了。从 Claude Code 的角度看它明明有很强的推理能力却因为缺少规则而给出了泛泛的“标准答案”然后被我打回重写。我统计过一笔账一个中型项目里每次新会话光是把技术栈、目录结构、代码规范、注意事项说清楚至少要花 300 到 600 个 token 的对话量而这些对话本身并不产生任何业务产出。更隐蔽的问题是行为不一致。上一轮你说“错误处理统一用 Result 模式”它记住了下一轮你没说它用了 try-catch。开会时同事问“我们不是定了规范吗”我只能苦笑——规范在 README 里躺着但 Claude Code 不看 README它只看这一轮对话里你给了什么。1.2 模板的本质把“约定”从对话里搬到文件里后来我意识到问题的根子在于我把“约定的载体”选错了。对话是易失的文件是持久的。就像带新人如果你每天都口头讲一遍岗位职责讲的人累听的人忘但如果你给新人一本入职手册他随时可以翻一天就能进入状态。Claude Code 的 CLAUDE.md 就是那本入职手册。所谓 claude-code-templates不是某个官方插件而是一整套约定文件的结构化方案。它的核心思路是把每个项目里恒定不变的规则——技术栈、目录结构、常用命令、代码风格、业务约束——从对话中抽离出来放进 Claude Code 会自动读取的文件里。会话开始时它自己看不需要你再啰嗦一遍。有人会问把规则写进 CLAUDE.md和写进 README 有什么区别区别在于读取方。README 是给人看的Claude Code 虽然也能 grep 到但它不会主动把 README 当作“必须遵守的规范”。CLAUDE.md 则会被 Claude Code 在启动时主动加载并作为系统级指令的一部分参与每一次回答。你不需要说“请参考 README 第 3 章第 2 节”它已经把规则内化到了上下文里。这一个差异直接改变了整个工具的可控性。2. 一套可落地的模板骨架三层 CLAUDE.md 怎么分2.1 全局层、项目层、会话层的职责边界我的模板库目前是三层结构每层解决不同粒度的问题。第一层是全局模板位置在~/.claude/CLAUDE.md。它存放的是与我个人强相关、和具体项目无关的偏好。比如我写 Python 时统一用ruff做 lint、pytest跑测试写 TypeScript 时统一用pnpm装依赖提交信息走 Conventional Commits我不接受 AI 在代码里留大段注释除非是解释复杂业务逻辑。这些规则我在任何项目里都希望遵守所以就放在全局层。第二层是项目模板位置在项目根目录的./CLAUDE.md。它存放的是当前项目的特异性知识技术栈版本、目录结构、启动命令、测试命令、数据库迁移方式、API 错误码规范、部署流程。这一层是 claude-code-templates 的核心因为项目不同这层的内容差异最大也最容易被 AI 搞错。第三层是个人覆盖层位置在项目根目录的./CLAUDE.local.md。这个文件通常不提交到 Git用来放你个人在这个项目里的“私有工作流”。比如我习惯在某个项目里用本地脚本跑构建或者本地环境变量和团队不一致这些写在CLAUDE.local.md里。它的加载优先级高于项目层能覆盖项目层里的某些约定但不会污染团队的公共配置。2.2 一个项目级 CLAUDE.md 的真实示例这是我在一个电商后台项目里实际用过的项目模板去掉敏感信息后大概长这样# 项目电商后台管理系统 ## 技术栈 - 前端React 18 TypeScript Vite - 后端Node.js Express PostgreSQL - 迁移工具Drizzle不要用 TypeORM - 部署Docker GitHub Actions ## 常用命令 - 启动开发环境npm run dev - 运行测试npm test - 单测一个文件npx vitest run src/utils/date.spec.ts - 构建npm run build ## 代码规范 - 组件用函数组件禁用 class 组件 - 类型定义放在 src/types/ 目录 - 错误处理统一用 Result 模式禁止裸抛 Throwing - 所有请求必须经过 src/request.ts 封装不直接调用 fetch ## 关键业务约定 - 订单状态流转只能通过 orderService.transition() 方法禁止直接改数据库字段 - 库存扣减必须放在事务里先扣库存再生成订单 - 金额字段用分为单位用 bigint 存储禁止浮点 ## 数据库 - 库名shop_admin - 连接串写入 .env.local不要提交 .env - 迁移命令npm run db:migrate这段模板看起来不复杂但非常有效。它把 AI 最容易踩的五个坑全部堵住了ORM 选错、错误处理风格漂移、订单状态被随意修改、金额用浮点、数据库连接串泄露。这五个坑不是我想象出来的是我在过去的代码评审里真实踩过、然后一条条沉淀到模板里的。2.3 加载顺序与文件命名逻辑关于加载顺序有一个关键点必须搞清楚Claude Code 在会话启动时会按优先级从低到高加载多个 CLAUDE.md 文件后面的会覆盖前面的同名指令。目前社区里最常见的约定是全局~/.claude/CLAUDE.md→ 项目./CLAUDE.md→ 本地./CLAUDE.local.md。如果你的项目里还有子目录./api/CLAUDE.md这种子目录级模板也会在编辑对应目录时叠加加载。理解这个层级结构非常重要因为它决定了你该把规则放在哪一层。我的判断标准是两条这条规则是否跨项目通用如果通用放全局如果不通用放项目。这条规则是否属于“我的个人习惯”且不想让团队成员被迫遵守如果是放本地覆盖层。把规则放错了层会造成团队协作时 AI 行为互相打架——比如 A 成员全局模板里写了“用 tabs 缩进”项目模板里写的是“用空格缩进”AI 就会无所适从。3. 把高频动作沉淀成斜杠命令从 /review 到 /test3.1 命令模板的存放位置与触发方式CLAUDE.md 解决了“背景知识”的问题但它不解决“操作流程”的问题。比如我想让 Claude Code 做一次代码审查如果没有模板我得每次手写“请检查我的改动重点看安全和性能按严重程度输出……”如果我把这段提示词打包成了一个命令那么只需要输入/review它就会执行一套固定的审查流程。这些命令的存放位置是.claude/commands/目录可以是项目级的.claude/commands/也可以是全局级的~/.claude/commands/。文件名就是命令名比如review.md对应/review。注意这里有个细节命令文件的后缀名用.md因为它的本质上是一份 Markdown 格式的提示词模板。每份模板还可以带一段可选的 YAML frontmatter用来声明命令的标题和描述但就算不带 frontmatter只写正文也能正常工作。3.2 打磨一份代码审查命令模板下面是我一直在用的/review命令模板你也可以直接复制去改--- title: 代码审查 description: 审查当前分支的未提交改动 --- 请对当前分支的代码改动进行一次完整审查。 审查范围 - 相对主分支的最近改动git diff origin/main 审查重点 1. 安全SQL 注入、XSS、敏感信息硬编码、越权访问 2. 规范是否遵循项目 CLAUDE.md 中的代码规范 3. 性能明显的 N1 查询、不必要的重渲染、大对象拷贝 4. 错误处理链路是否完整是否可能吞掉异常 输出格式 - 按文件分组列出问题每条标注严重程度P0必须修复/ P1应修复/ P2建议优化 - 每个问题给出具体的修改建议直接给出代码 - 最后用一个表格汇总所有问题并给出总体结论这里的设计意图是把审查标准写死在模板里而不是依赖 AI 临场发挥。你会发现我特意标注了“git diff origin/main”因为如果不指定 diff 范围AI 可能把整个仓库都看一遍既慢又跑题。命令模板的目的就是消除这种不确定性。3.3 命令模板的三个设计原则第一一个命令只对应一个稳定的工作流。不要做一个叫“/everything”的命令要拆成/test、/commit、/explain、/db-migrate这样的小命令。命令拆得越细每次执行的行为就越可控。第二命令模板里不要重复项目规范直接引用即可。比如/review模板里写了“是否遵循项目 CLAUDE.md 中的代码规范”而不是把项目规范抄进来。为什么因为项目规范会变如果命令里复制了一份改的时候就必须同时改两个地方很快就不同步了。第三给命令预留输入参数。Claude Code 支持以$ARGUMENTS的形式接收用户在命令后输入的额外文本比如/test 只跑 user 模块。模板里可以这样写请执行以下测试任务 $ARGUMENTS 要求 - 如果未指定范围默认运行全量测试 - 测试失败时先排查失败原因再修复不要盲目重跑这样命令就有了开放性不会被写死成一种固定用法。4. 子代理模板给 AI 分配专职角色4.1 什么是子代理和命令有什么区别斜杠命令解决的是“一次性任务”的问题子代理Subagents解决的则是“专职角色”的问题。两者最直观的区别是命令是一次性的流程AI 执行完就回到主对话子代理是一个独立配置的角色有自己的系统提示词、工具权限乃至模型偏好可以像一位同事一样被邀请进入某个任务并持续工作。子代理的配置文件放在.claude/agents/目录和后缀.md形式类似只是 frontmatter 更丰富。最常用到的字段包括name、description、tools。其中description的质量直接影响主代理能不能“想起来”调用它。如果你的 description 写得含糊主代理遇到相关任务时可能根本不会分发给它。4.2 reviewer、debugger、documenter 三个角色模板我最早试水的时候配了三个子代理至今仍在用非常适合作为入门参考。一个是审查专员reviewer。它的定位是“只读不改”所以我给它配置的都是只读类工具--- name: reviewer description: 代码审查专家专注于发现代码中的安全漏洞、性能问题和规范偏差。适合在改动完成后调用。 tools: Read, Grep, Glob, Bash --- 你是一位有十五年经验的软件架构师擅长代码审查。你只负责发现问题并提出修改建议绝对不直接修改代码。 审查时遵循以下步骤 1. 先了解项目结构和当前改动范围 2. 按安全、性能、规范、错误处理的顺序逐项检查 3. 输出结果按严重程度排序每条必须给出具体修改建议第二个是排查专员debugger。它的定位是“快速定位根因”所以我允许它执行 Bash 来复现问题--- name: debugger description: 调试专家擅长分析报错堆栈、复现问题、定位根因。适合在处理异常和故障时调用。 tools: Read, Grep, Glob, Bash --- 你是一位经验丰富的调试专家。你的任务是快速定位问题的根因而不是直接给出修复方案。 步骤 1. 复现问题收集报错信息 2. 缩小范围定位到具体函数 3. 输出根因分析报告包含证据链 4. 如果缺少关键信息主动向用户询问第三个是文档专员documenter。它负责把代码变更整理成文档或 commit message--- name: documenter description: 技术文档专家擅长将代码变更转化为清晰规范的提交信息、变更日志和技术文档。 tools: Read, Grep, Glob --- 你是一位技术文档工程师。你阅读代码改动然后输出符合 Conventional Commits 规范的提交信息。这三个子代理各有明确的边界不会互相抢活。reviewer 只审查不改debugger 只定位根因不直接修复documenter 只读代码不做分析。职责分离得越干净AI 的行为就越可预测。4.3 子代理模板的调参经验tools 的收与放子代理的tools字段是我调整最频繁的地方核心原则是“最小权限”。你要只给它完成职责所必需的工具多给一个都可能惹出麻烦。比如 reviewer如果我给它配上编辑类工具它在审查过程中可能手一滑就把代码改了——而且改得不一定对我还得在 diff 里发现它背着我动了代码。现在我只给它只读工具它想说“这里应该用 Optional 而不是 null”就必须写建议再由主代理或者我来执行修改这样每一步都有人类确认。不过 tools 收得太紧也会有问题。debugger 如果不允许运行 Bash就没法执行测试复现问题排查能力直接砍半。所以我给 debugger 保留了 Bash让它能跑日志、跑单测、查环境变量。除了工具权限子代理的文件数量也要控制。我一开始配了七八个子代理结果主代理经常不知道该选谁反而拉低了响应速度。精简到三个高价值的之后调用准确率明显提升。子代理不是越多越好而是角色越分明越好。5. 让规则自动执行Hooks 模板与自动化脚本5.1 Hooks 的触发时机CLAUDE.md 是静态的“入职手册”斜杠命令是手动发起的流程而 Hooks 是动态的“自动化开关”——它能在特定事件发生时自动执行脚本不需要用户显式要求。Claude Code 里比较常用的 Hook 触发点大致有几种会话启动SessionStart、工具调用前PreToolUse、工具调用后PostToolUse、用户通知Notification等。每个触发点接收一组事件参数你可以在脚本里读取这些参数并决定后续动作。Hooks 对模板库的补充价值在于它能把“约定”变成“强制”。CLAUDE.md 里写“不要直接调用 fetch”聪明的 AI 会遵守但忙起来也可能疏忽。如果你在 PreToolUse 里挂一个脚本在检测到工具的输入或用户行为触发了特定关键词时返回一个阻断信号约定就从软约束变成了硬约束。5.2 一个实用的 SessionStart 脚本模板我用的最频繁的一个 Hook 是 SessionStart。它的作用是每次新会话开始后自动打印一段项目状态摘要让 Claude Code 在动手前先“看一眼”当前环境。脚本逻辑大概这样#!/usr/bin/env bash # hooks/SessionStart.sh # 打印当前分支和最近一次提交 echo Current Branch git branch --show-current echo Last Commit git log -1 --oneline # 打印是否有未提交改动 echo Working Tree Status git status --short # 打印项目依赖变化可选 if [ -f package.json ]; then echo Dependencies cat package.json | jq .dependencies | keys | join(, ) fi这个脚本本身不做什么高深的事但它把一个非常重要的信息喂给了模型的上下文当前在哪个分支、有没有未提交的改动、最近一次提交是什么。很多 AI 犯错就是因为不知道“自己处于什么状态”自动打印上下文能显著减少这类错误。另一个常用场景是在 PostToolUse 里监听文件编辑事件——当 AI 刚改完文件后自动跑一遍 lint 或格式检查把结果反馈给主对话这就等于给 AI 加了一道“写完即检查”的工序。5.3 Hooks 的重量控制自动化与心流的平衡用 Hook 时要格外警惕“自动化陷阱”——脚本太重反而破坏使用节奏。我第一次写 SessionStart 时放了大量信息输出环境变量、内存状态、所有依赖版本、开放端口列表结果每次会话启动都要等两三秒而且输出把上下文塞得很满AI 反而抓不住重点。后来我把输出砍到了只剩分支、最近的提交、未提交改动三行。建议你遵循一条原则Hook 脚本只负责“让 AI 知道必要的信息”不要替 AI 做判断。另外不同操作系统上路径和命令可能有差异如果模板要在团队里共享尽量用跨平台写法或者在文档里标注依赖项。Hooks 脚本也属于模板库的一部分必须纳入版本管理否则同事拉下来根本跑不起来。6. 模板库的组织、版本管理与团队共享6.1 用 Git 管理你的模板库我在~/.claude/目录下直接建了一个 Git 仓库把 CLAUDE.md、commands 和 agents 都纳入了版本管理。好处是每次改动都有历史记录哪条规则让我引入了 buggit log 一看就清楚。另一个好处是“试错成本”变低了——新模板可以先在分支上实验不行就回滚不用怕把自己的主配置改坏。模板库的目录结构我保持了扁平化~/.claude/ ├── CLAUDE.md ├── CLAUDE.local.md ├── settings.json ├── commands/ │ ├── review.md │ ├── test.md │ └── commit.md └── agents/ ├── reviewer.md ├── debugger.md └── documenter.md注意CLAUDE.local.md是不进 Git 的我把它加进了.gitignore因为里面装的都是个人本地习惯提交了反而会污染别人的环境。但你个人的CLAUDE.local.md也要保持备份我一般把它放在一个私有仓库里不公开。6.2 团队模板仓库的落地路径模板库的价值在团队场景下会被放大好几倍。如果整个团队共用一套命令模板和子代理配置那么每个人得到的 AI 辅助水平就是一致的而不是“老张调教得很强新来的小李还在被 AI 瞎糊弄”。具体落地有三种路径。第一种最轻量把.claude/目录直接放进项目代码仓库随代码一起评审、一起演进而非过期。这也是我推荐大多数团队采用的方式因为项目级模板本来就跟着项目走。第二种建一个独立的模板仓库通过脚本同步到每个成员的本地目录适合要管理全局级模板的团队。第三种使用公司内部的配置分发机制把模板作为开发环境的一部分统一推送适合大规模团队。无论用哪种方式最关键的一点是模板变更必须走评审。不要默认“模板是配置文件改了不碍事”。我见过一次事故有同事在全局模板里加了“所有日志统一输出为 JSON”的规则结果其他人的项目 AI 行为全部改变日志格式乱了一周。模板是 AI 行为的源代码和业务代码一样需要认真对待。6.3 我踩过的两个坑第一个坑是路径写死。早期我在命令模板里写了一个绝对路径/Users/myname/work/templates/checklist.md结果同步给同事后命令直接失效。后来我改成在命令里先定位项目根目录再拼接相对路径或者用仓库相对路径描述才彻底解决。模板里尽量不要出现只有你的机器上才存在的路径。第二个坑是嵌套混乱。某次我不小心同时配置了项目级和子目录级的 CLAUDE.md层级之间又有冲突的规则AI 表现得反复无常。后来我明确了“子目录级模板只描述子目录特有的逻辑不覆盖项目级约定”。额外补充一点子代理的 system prompt 与主对话的 CLAUDE.md 之间的关系容易被忽略。子代理加载时是否继承项目 CLAUDE.md 的实际行为取决于具体版本和配置方式所以我在子代理模板里会明确写一句“遵循项目 CLAUDE.md 中的规范”防止子代理完全无视项目背景。7. 模板不是越厚越好避坑经验与复盘7.1 三层的内容密度怎么把握给模板做“加法”是顺手的事做“减法”才是功夫。我的经验是CLAUDE.md 控制在 100 到 200 行以内超过这个量AI 的注意力会被稀释重点规则反而容易被淹没。斜杠命令的正文控制在 30 行左右太长就会变成一份没人用的小册子。子代理的 system prompt 也不是越长越好与其堆砌一堆形容词不如用步骤化描述让行为路径清晰。怎么判断一条规则该不该写进模板有三个标准这条规则是否被 AI 违反过两次以上这条规则是否导致了严重的后果这条规则是否无法通过代码本身表达如果三个都是否就不写。比如“变量名要有意义”这种废话AI 永远不会犯写进模板只会增加噪音。7.2 模板维护节奏每周一蹲守修订我给自己定了一个维护节奏每周五下午花十五分钟回顾这一周的对话。凡是出现了我不得不重复纠正 AI 的行为我就把它写进模板凡是模板里一条规则这一整周都没有触发过我就考虑删掉。这样能保证模板库永远在自我更新而且每个条目背后都有真实案例支撑。这种维护习惯还有一个额外的好处你会慢慢发现自己反反复复纠的那些问题往往是同一个根因。比如我连续三周都在纠正“AI 不写测试就急着交付”后来我把/test命令模板改成默认先写测试再写实现并且在 CLAUDE.md 中加了“任何功能改动必须附带测试”的硬规则AI 的行为才真正改变。7.3 最后分享一条实测心得折腾了 claude-code-templates 这段时间我最深的体会是模板的真正价值不是替我省了多少 token而是让交互的行为方差变小了。没有模板的时候Claude Code 像一位天赋很高但情绪不稳定的外包工程师有模板之后它变成了一位稳定执行规范的合作者。你需要做的不是记住每条规则而是让模板成为你和它之间共同的工作契约。如果你还没开始整理自己的模板库今天就可以从一句 CLAUDE.md 开始——把最近一次你不得不重复交代的规则写进去然后看看下一次会话会发生什么变化。我猜你也会和我一样写了几条之后就停不下来了。