Claude Code模板体系：用CLAUDE.md与子智能体终结重复劳动

如果你也在用 Claude Code大概率经历过这种尴尬新开一个会话把项目背景、测试命令、目录约定从头再讲一遍讲完才发现上轮刚讲过。我后来的解法是把所有能固化的协作方式整理成一个模板仓库命名为 claude-code-templates。这个项目不只是一堆 Markdown 文件而是一整套覆盖 CLAUDE.md、斜杠命令、子智能体和技能的模板体系目标是让新项目在 5 分钟内继承我过去几百个小时里试出来的工作方法。下面我会把这套模板体系从设计思路到落地细节完整拆开讲适合已经开始用 Claude Code、但觉得每次会话都像从零开始的开发者也适合想在团队里统一 AI 协作方式的工程团队。1. 模板化之前Claude Code 工作流里的重复劳动比你想象的多1.1 每天重复十遍的项目背景说明先做个实验打开一个新的 Claude Code 会话什么都不输入直接问它这个项目怎么跑测试。如果你的仓库稍微复杂一点比如是 pnpm monorepo或者某个服务依赖本地 Docker 容器它大概率会给出一个看起来合理但实际跑不通的答案。原因很简单——它没有记忆。上一轮会话里你辛辛苦苦确认过的东西这一轮全都不存在。我统计过自己前两个月的使用习惯每次会话开头平均要花 8 到 12 分钟交代背景包含但不限于技术栈、常用脚本、目录约定、代码风格、禁区清单。这些信息不是不能说而是反复说太浪费更致命的是每次说的版本还不一样。今天心情好就多说一句架构约束明天赶进度就漏掉一段Claude 的行为随之飘忽不定。1.2 模板的价值不是约束而是减少不确定性我把模板理解成入职文档而不是镣铐。你带新人不会指望他通过读源码自行领悟团队规范同理Claude 也不应该靠每次对话临时猜。模板承担的是把所有确定性的内容固定下来让模型的上下文预算全部花在面对新问题上。这里有个反直觉的地方很多人觉得模板写得越多越严谨其实不是。CLAUDE.md 就像一个聊天窗口的开场白它的篇幅是有限度的内容过载反而会让关键约束被稀释。好的模板是少而准——只写那些违反之后代价很大的事以及那些靠猜一定猜不对的事。把这条想清楚后面设计所有模板都会有方向。1.3 一套完整的模板体系至少要覆盖四类对象我的模板仓库最终拆成了四个层面每个层面解决不同的问题也放在不同的目录里模板层存放位置典型作用变更频率会话记忆~/.claude/CLAUDE.md、./CLAUDE.md交代全局习惯与项目事实低频随项目演进斜杠命令~/.claude/commands/、.claude/commands/把高频操作变成一条指令中频随工作流新增子智能体.claude/agents/某一类角色的完整工作方式低频重在设计技能包.claude/skills/带示例和脚本的复合能力中频随实践沉淀这四层不是并列关系而是递进关系CLAUDE.md 负责底线斜杠命令负责入口子智能体负责深度思考技能包负责可执行的产物。搞清楚每一层的边界比收集网上的各种模板片段重要得多这也是我在整理 claude-code-templates 时最先想明白的事。2. CLAUDE.md 模板层全局习惯与项目约束的分工策略2.1 全局模板~/.claude/CLAUDE.md只写我习惯怎么做全局模板是启动每个会话都会自动加载的所以它的内容必须对任何项目都成立。我在这里放的只有三类东西工作习惯、通用禁区、输出偏好。# 通用工作习惯 - 动手改代码前先完整读一遍涉及的文件 - 新增依赖前先说明理由等待我确认 - 代码注释写中文与团队讨论记录保持一致 - 提交信息遵循 Conventional Commits 格式 # 通用禁区 - 不主动重构与任务无关的代码 - 不删除我未明确要求删除的内容 - 不修改锁文件和依赖版本除非我要求 # 输出偏好 - 解释方案时先给结论再给原因 - 修复 bug 后说明根因不要只贴 diff注意看这里面没有任何项目相关的词。一旦全局模板里出现我们项目用的是 pnpm这类句子你换到另一个仓库时就会被污染。全局模板的维护原则是删减比增补重要凡是只对某个仓库成立的约束一律挪到项目模板里。2.2 项目模板./CLAUDE.md只写这个仓库的事实项目模板的作用是告诉 Claude 这个仓库特有的、外部无法推断的知识。我的常规结构是五段式# TechStack - pnpm workspace monorepo - packages/appReact Vite TS - packages/serverNode Fastify - 数据库PostgreSQL 16docker compose 管理 # Commands - install: pnpm install --frozen-lockfile - test: pnpm --filter app/* test - lint: pnpm lint - dev: pnpm --filter app/server dev # 目录约定 - packages/app/src/pages 下面按路由组织 - 公共组件放在 packages/app/src/components/ui # 关键约束 - 页面改动必须通过 lint 与类型检查 - 对外 API 变更需要同步更新 openapi.yaml # 参考文档 - docs/architecture.md - docs/testing-guide.md有几个容易被忽略的点。第一Commands里的命令要写在这里手动跑过确认没问题的版本不要照抄 README 里可能过期的脚本。第二参考文档这个段落善用路径引用CLAUDE.md 本身不用把文档全文塞进来只需要让模型知道去哪读这既能控制记忆体占用又能保证文档更新后模型拿到的永远是最新内容。第三项目模板要跟着仓库提交而不是留在本机否则同事新 clone 下来还是一张白纸。2.3 CLAUDE.local.md 与子目录模板的作用域CLAUDE.local.md 是容易被忽略的第三层。它和 CLAUDE.md 叠加加载专门用来放只属于我个人的笔记——比如这个仓库里哪个模块历史包袱重、哪个人写的代码要小心这类主观判断。它不参与团队共享所以默认应该加进 .gitignore。对于 monorepo 这种大仓库还可以在子目录里放独立的 CLAUDE.md。Claude 进入子目录工作时会叠加加载对应路径下的模板非常适合给 packages 里差异巨大的模块单独写约束。这样母仓库的 CLAUDE.md 不用臃肿子模块又能拿到足够精准的上下文。2.4 一版可直接改用的项目模板骨架如果你不想从零开始可以直接拿下面这个骨架改它是我根据不同项目迭代出来的通用版删掉了所有业务细节只留结构和占位说明# 项目概况三句话以内说明这个仓库是什么 # 技术栈列表形式注明版本约束 # 常用命令构建、测试、lint、dev各一行 # 目录结构只写最关键的入口 # 协作约定代码风格、提交规范、API 变更流程 # 禁区任何违反代价很高的事 # 参考文档path 形式的链接骨架写完后做一次验证新建一个空目录把 CLAUDE.md 放进去问 Claude请复述这个项目的三条关键约束。如果它答得含糊说明模板里废话太多压住了关键信息该删了。3. 斜杠命令模板把高频操作固化成可复用指令3.1 命令模板的存放位置与命名规则斜杠命令本质上是 Markdown 文件文件名去掉.md就是命令名。用户级命令放在~/.claude/commands/任何项目可用项目级命令放在.claude/commands/只对当前仓库生效。我建议的规则是通用流程例如review、commit放全局依赖仓库结构的那部分操作放项目目录。同名命令以项目目录为准这样团队可以在不过度污染全局的情况下覆盖默认行为。3.2 用 Frontmatter 给命令声明行为一个标准的命令模板长这样--- description: 对目标文件做一轮 Code Review argument-hint: file-path agent: code-reviewer allowed-tools: Read, Grep, Glob --- 请对 $ARGUMENTS 做一次完整的 Code Review重点从以下几个方面检查 1. 逻辑正确性与边界条件 2. 数据流是否清晰有没有隐式依赖 3. 错误处理路径是否完整 4. 可测试性是否容易为这段代码补测试 每个问题给出文件与行号最后按严重程度分级汇总。description会显示在命令列表里也是 Claude 判断何时该用这条命令的依据所以要写成触发条件动作而不是空洞的形容词。argument-hint是给使用者看的占位提示。agent可以把命令交给特定的子智能体执行这在参数较多时很管用。allowed-tools则限制执行路径避免一个简单的 review 操作里模型顺手去跑 Bash。3.3 参数、文件引用与 Bash 执行命令模板里最常用的变量是$ARGUMENTS它指用户在命令后输入的全部内容。比如/review src/utils/date.ts那么$ARGUMENTS就是src/utils/date.ts。如果命令需要读某个文件作为上下文用路径语法把文件内容加载进来请结合 docs/api-conventions.md 中的规范检查 $ARGUMENTS 是否合规。需要跑命令时在模板里以!开头写 Shell 命令Claude 会先执行再继续--- description: 统计代码库内的 TODOs --- 先执行 !rg TODO|FIXME --stats再按文件维度汇总 TODO 与 FIXME 的分布标记超过 10 个的文件。这套组合让命令模板不只是一段固定 Prompt它变成了一个微型工作流可以读文件、跑命令、做完后再让模型总结分析。3.4 实测有效的高频命令模板我实际在用的三个命令模板适合直接抄review.md就是一个带评审维度清单的 review 命令上面已经展示过了。它配合code-reviewer智能体使用时产出质量明显高于随手一句帮我看看这段代码。commit.md根据!git diff --cached的结果生成提交信息模板里明确要求按 Conventional Commits 输出并且禁止出现 update fix 这类含义模糊的词。triage.md接收一个日志文件路径作为参数命令体要求先!tail -200 $ARGUMENTS再根据 ERROR/WARN 分布输出时间线分析最后给出最可疑的三条错误线索。这类命令把怎么排查的路径固化了比每次现想更可靠。这里有个经验命令模板不要追求一次输入就完美而是要追求输出路径可预期。哪怕它偶尔判断得不好只要步骤稳定你就能在稳定的基础上迭代而不是在随机性上打转。4. 子智能体与技能模板让团队协作经验沉淀为资产4.1 子智能体把角色与工作方式写进独立模板子智能体Agent是刻画出的一种角色边界。文件放在.claude/agents/一个 Markdown 文件对应一个角色--- name: code-reviewer description: 适合执行代码评审在需要检查合并请求质量时使用 tools: Read, Grep, Glob, LS --- 你是一名有十年经验的资深工程师负责独立完成代码评审。 你的评审原则 - 先理解改动意图再检查实现细节 - 对可运行性问题给出具体行号 - 不吹毛求疵风格问题只抓实质缺陷 - 每个问题附带修改建议按 P0/P1/P2 分级关键在两点一是description要写明触发场景它是 Claude 决定是否启用该角色的参考二是tools要按角色需要的最小集合来声明——评审不需要Bash调试则需要放开Bash。角色模板的价值在于它把资深评审应该看什么从每次对话的随机发挥变成了团队统一的标准。4.2 技能包带示例和配套脚本的复合能力技能Skills与命令不同它是带配套资源的复合包。目录结构通常是.claude/skills/技能名/SKILL.md技能名是一个短横线风格的标识如write-unit-tests。SKILL.md 的 frontmatter 至少包含name和description正文写完整的执行流程除 SKILL.md 之外目录里可以放示例文件、模板片段、辅助脚本这些资源会在技能被调用时一起作为上下文加载所以技能包本质上是一个自包含的工作台。这里有个容易混淆的地方斜杠命令是一次性动作技能是持续可用的能力。命令像快捷键技能像工具箱——盒子里的东西需要配套协作才能完成一个像样的交付。我举一个写单测技能的例子SKILL.md 里说明当用户要求为某个模块补测试时按以下流程执行流程包含先读源文件、识别依赖、生成用例清单、按团队模板落盘、跑测试验证五步然后目录里放一份团队认可的测试文件模板一个包含边界值样例的 fixtures 文件以及一个生成测试骨架的脚本。命令解决的是入口技能解决的是产物——它确保每次产出都符合同一套质量基线也把团队里怎么写测试才算好的标准落到了磁盘上。4.3 从单个巨型 Prompt 到角色矩阵的演进我最早的用法非常简单粗暴把所有要求堆在一个 CLAUDE.md 里。结果改评审风格会影响调试行为加一条输出规范可能导致其他任务都变啰嗦牵一发动全身。后来拆成角色矩阵后情况完全不同了写需求分析去review命令配code-reviewer角色解决线上问题去triage命令配debugger角色需要重构时再临时加载refactor角色。每个角色只维护自己的模板变化的影响被限制在局部改代码评审的尺度再也不用担心污染别的任务。演进过程中我总结了一个经验判定该用子智能体还是技能看这个任务重思考还是重产出。偏重思考判断的用子智能体比如代码评审、方案设计、缺陷归因偏重标准产出的用技能包比如写测试、发版本说明、生成变更日志。两者经常配合出现——命令模板里agent字段指向子智能体子智能体的输出再交给技能包来规范化这个组合在实践里比任何单一模板都稳定。5. claude-code-templates 仓库的组织方式与调试心得5.1 仓库的目录结构与部署方式我维护的 claude-code-templates 仓库是这个结构claude-code-templates/ ├── global/ │ ├── CLAUDE.md │ └── commands/ │ ├── review.md │ ├── commit.md │ └── triage.md ├── project/ │ ├── CLAUDE.md │ ├── CLAUDE.local.md │ ├── commands/ │ ├── agents/ │ │ ├── code-reviewer.md │ │ ├── debugger.md │ │ └── refactor.md │ ├── skills/ │ │ ├── write-unit-tests/ │ │ └── incident-analysis/ │ └── settings.json └── README.mdglobal下的内容通过符号链接或安装脚本放到用户目录避免直接复制导致后续更新失联project下的模板作为种子项目新仓库直接拷贝进去再改动。对团队来说project部分提交到代码仓库里最合理CLAUDE.md、agents、skills 能跟着代码一起评审、一起走版本历史这是个人使用和团队协作最大的分水岭。5.2 验证模板是否真的生效模板写出来不算完关键是要验证它到底有没有被加载。我一般用三个手段进入会话后输入/context旧版本是/memory查看当前实际加载的 CLAUDE.md 列表确认全局、项目、子目录三层分别命中了哪些。输入/help并滚动到自定义命令区域确认新加的斜杠命令是否出现。注意项目命令只有在对应目录下启动会话时才可见。需要排查加载细节时用claude --debug启动会话日志会打印模板文件的装载路径和解析结果比对着文档猜快得多。另外验证命令模板时建议用空目录测试项目层用任意目录测试全局层两侧分开验证否则出了问题很难定位是哪一层在影响行为。5.3 我在使用过程中踩过的三个坑第一个坑是 CLAUDE.md 内容爆炸。我曾经把一个项目的模板写到两百多行结果模型在关键约束上的表现反而变差了。原因不难理解上下文里的信息量太大指令之间的优先级被稀释。后来我把大部分内容改成引用文档模板本体压缩到六七十行效果立竿见影。第二个坑是命令模板里的绝对路径。最开始写 review 命令时我在里面放了/Users/me/work/project/...换台机器立刻失效一开始还以为是模板没同步排查了半天才发现是路径在别的机器上根本不存在。从那次之后我给自己定了一条规矩模板里出现/Users、C:\这类绝对路径时一律改写路径信息交给$ARGUMENTS或者相对路径。排查的顺序建议是先看/context确认模板有没有加载再看命令体里引用的外部资源能否访问最后才怀疑是模型理解的问题。第三个坑是 settings.json 里把权限卡得太死。为了安全我一度禁止了所有 Bash 权限结果技能包里依赖脚本的流程全部失效。后来改成按模式放行比如Bash(pnpm run *)、Bash(node scripts/*)既保住了安全底线又没把自动化流程堵死。权限配置要跟着模板走每加一个模板都要重新审视它的最小权限集合。最后分享一个保存这些经验的小技巧我给 claude-code-templates 加了一个 CHANGELOG 文件每增删一个模板或修改一段规则都顺手记一句为什么改。时间一长你会发现这份 CHANGELOG 比模板本身还值钱因为模板是最终状态而 CHANGELOG 记录的是每个决策背后的上下文。下次再做模板版本升级或者给团队讲设计思路时翻一翻就全想起来了。