Claude Code模板体系实战：从CLAUDE.md到命令、子代理与技能

1. 给 Claude Code 建一套模板到底是在解决什么问题用上 Claude Code 之后我踩过的一个最典型的坑就是同一个项目今天让它排查日志、明天让它写接口、后天让它做 code review每一轮都要把项目背景、编码规范、常用命令重新贴一遍。贴完还常常不服管改着改着就偏离了团队约定。后来我认真把 templates 这件事做起来情况立刻不同了。所谓 claude-code 模板并不是某个单一文件而是一整套把“你希望 AI 怎么工作”固化成可复用资产的做法。核心解决的不是“少打几个字”而是“每次进入项目的 AI都像同一个熟悉项目的老同事”。很多人以为模板就是写几个提示词存起来。真正用下来你会明白Claude Code 的模板体系包含四个层次项目说明书、斜杠命令、子代理、技能脚本。它们分别解决不同的问题组合在一起之后你就拥有了一套不依赖个人记忆力的团队规范。它适合谁适合所有在真实工程里高频使用 Claude Code 的开发者尤其是维护多个仓库、需要反复执行固定任务、或者想让团队成员共享同一套 AI 工作方式的场景。这套东西的价值我总结成一句话模板是给 AI 的“入职文档”。新人入职要看公司规章、看项目架构、看代码规范AI 也一样。你把它该知道的、该遵守的、该按什么流程做的事全部前置成文件它就不会每次都在同一个地方犯迷糊。下面的内容我会从文件组成、命令写法、编排思路和踩坑经验四个角度展开全部来自我实际项目里的做法可以直接抄。2. 模板体系拆解CLAUDE.md、命令、子代理与技能2.1 CLAUDE.md 是把项目背景固化成文件的起点Claude Code 对 CLAUDE.md 有天然支持。放在项目根目录的 CLAUDE.md 会被自动读取相当于每一次会话开始前AI 都会先读一遍这个文件然后带着这些背景信息工作。实际测试下来文件内容会被作为系统级上下文的一部分处理优先级相当高。这意味着你不需要再每次手动说“我们的后端是 Java 17、用 Maven、代码规范是 Google Style”它一开始就知道。我项目里的 CLAUDE.md 长这样# 项目说明 这是一个面向电商中台的订单服务使用 Spring Boot 3.2 MyBatis Plus 数据库为 MySQL 8.0部署在 Kubernetes 上。 # 常用命令 - 构建mvn clean package -DskipTests - 单测mvn test - 启动本地mvn spring-boot:run -Dspring-boot.run.profileslocal # 代码规范 - Controller 只做参数接收和响应封装不写业务逻辑 - Service 层必须开启事务注解 Transactional - 所有对外接口的响应统一使用 ResultT 包装 - 数据库字段命名使用下划线Java 属性使用驼峰 # 项目结构 - controller/接口层 - service/业务逻辑 - dao/数据访问层 - domain/实体对象 - dto/数据传输对象 # 注意事项 - 本地联调依赖 order-mysql 这个 Docker 容器启动前先用 docker compose up -d - 修改数据库结构时必须同步更新 dao 层和 domain 层 - 日志必须使用 org.slf4j.Logger不能直接用 System.out注意 CLAUDE.md 不是让你写一篇论文而是把高频、稳定、会影响结果的信息写进去。我会定期维护它一旦发现 AI 反复问同一类问题就说明这里漏了信息。还有一个小技巧CLAUDE.md 支持放在多个层级全局的用户目录~/.claude/CLAUDE.md、项目根目录、子目录都可以放。全局文件放个人偏好比如“不使用 print 调试”“代码里中文注释”项目文件放仓库信息子目录文件适合放微服务的局部规范。三层叠加AI 会自动按层级合并读取。2.2 斜杠命令模板把固定动作变成一句话CLAUDE.md 解决的是“AI 知道”斜杠命令解决的是“AI 会做”。Claude Code 支持自定义斜杠命令命令本质是一个 Markdown 模板文件放在.claude/commands/目录下。全局命令放~/.claude/commands/项目命令放项目的.claude/commands/。文件里可以写 YAML 格式的 frontmatter 说明参数正文就是你希望 AI 执行的一套指令。我把日常最高频的“写接口”做成了命令模板文件名叫add-api.md--- description: 新增一个 REST 接口包含完整的分层实作 argument-hint: [接口路径] [请求方法] [功能说明] --- 请帮我新增一个接口参数如下 - 接口路径{argument-0} - 请求方法{argument-0} # 这里实际按你的参数个数写成 {argument-1} - 功能说明{argument-2} 要求 1. 在 controller 包下新增对应的 Controller 类 2. 新增 Service 接口和实现类实现类加事务注解 3. 新增 DTO 类包含参数校验注解 4. 返回统一使用 ResultT 包装 5. 完成后列出所有新增和修改的文件清单 实现前先阅读 CLAUDE.md 中的项目结构和代码规范。实际使用时只需要输入/add-api POST /order/create 创建订单AI 就会自动按这个模板完整走一遍流程。这类命令最典型的用途是写接口、修 bug、做 code review、补单测、生成提交信息。一个共同点是这些动作每次都包含固定的检查清单。模板让你不需要把同样的步骤重复说第二遍。2.3 子代理模板给不同任务配置不同的“专家”Claude Code 还支持子代理通过在.claude/agents/目录下放 Markdown 文件来定义。子代理相当于给 AI 设定一个独立角色它有自己的系统提示词和可访问工具集。和当前会话的主代理不同子代理每次以独立上下文运行往往更专注、更不容易被前面聊乱的内容带偏。做代码审查、安全扫描、数据库脚本检查这类任务时子代理的效果好得多。我常用的一个子代理模板backend-reviewer.md--- name: backend-reviewer description: Java 后端代码审查专家专注于代码质量和事务安全 tools: Read, Grep, Glob --- 你是一位有 10 年经验的 Java 后端架构师擅长 Spring Boot 项目审查。 审查时重点关注 - 事务边界是否正确是否出现跨 Service 调用导致的事务失效 - Controller 层是否混入了业务逻辑 - 数据库查询是否存在 N1 问题 - 统一返回结构是否被绕过 - 并发场景下是否有竞态条件 输出格式 1. 问题清单按严重程度排序 2. 每个问题给出文件路径和行号 3. 修复建议必须具体到代码片段 4. 没有问题的部分也要简单说明在对话中输入backend-reviewer 审查一下订单模块新增的代码Claude Code 会切换到这个子代理来处理。注意子代理的上下文是独立的主对话里聊过的内容它看不到。如果你希望它了解背景要么在指令里描述清楚要么给它指定读取某个文件。这个特性既是优点也是限制需要慢慢体会。2.4 技能模板把多文件、多步骤的复杂流程封装起来除了命令和子代理还有一种更重的模板形态叫技能Skills。技能通过SKILL.md文件定义可以附带多个参考文件适合封装那种包含多个步骤、需要读取多个资料、甚至要执行脚本的复杂流程。技能和命令的区别有点微妙命令更像是一个指令宏技能则是一份“操作手册”AI 会按手册里的步骤逐步执行必要时可以配合工作流脚本。用一个实际案例说明。我给“数据库迁移”做了一套技能模板SKILL.md内容简要如下--- name: db-migration description: 数据库版本迁移的标准流程 --- 在执行数据库迁移时按以下步骤操作 1. 先读取 migrations/ 目录下的已有脚本确认当前版本号 2. 使用项目内的模板生成新的迁移脚本命名格式为 V{版本号}__{描述}.sql 3. 检查脚本中是否包含 DROP 语句如有要求必须二次确认 4. 执行前先运行 mvn flyway:validate 校验脚本完整性 5. 执行完成后打印当前版本号并核对 schema 变更记录 附典型字段类型变更对照表见 files/column-type-mapping.md技能的好处是它的知识可以累积。同一个技能目录下你可以持续往 files/ 里加文档AI 每次执行这个技能时都会把这些文档作为参照。我第一次用技能时只觉得它比命令更“重”用久了才明白复杂场景下必须用这种带知识库的模板否则 AI 只能靠临场发挥。简单任务用命令复杂任务用技能这个分寸在实际操作里非常关键。3. 从零到可复用打造一套开箱即用的模板库3.1 模板目录的结构设计与版本管理如果你只在一两个项目里用 Claude Code直接把命令文件放在项目下就够了。但如果像我一样维护几个仓库还带着团队一块用模板的存放方式和版本管理就必须讲清楚。我推荐的做法是把模板本身做成一个独立仓库结构如下claude-code-templates/ ├── CLAUDE.md ├── commands/ │ ├── add-api.md │ ├── fix-bug.md │ ├── review.md │ └── commit-msg.md ├── agents/ │ ├── backend-reviewer.md │ └── sql-checker.md └── skills/ └── db-migration/ ├── SKILL.md └── files/ └── column-type-mapping.md这个仓库通过 Git 管理打上版本标签。各项目使用时在项目根目录建一个.claude/目录把需要的命令、代理文件软链接过来或者干脆用脚本同步过去。我目前用的是一个简单的 shell 脚本只同步commands和agents两个目录项目特有的模板仍然留在项目内部。这样既能共享通用资产又不会把项目特殊逻辑强制带到别的仓库。版本管理的时候有一个细节模板文件会频繁变动尤其是命令里的检查清单每次更新都可能影响 AI 行为。我建议模板仓库的提交信息也写成“模板变更”的格式标明影响范围。这次改动是只影响新命令还是会改变已有命令的行为必须在提交信息里写清楚。否则过了两个月你根本想不起来某个命令的行为是哪次提交改掉的。3.2 覆盖高频场景从代码审查到提交信息的一整套模板我把实际项目中最常用、沉淀价值最高的模板场景按优先级列一下。这个优先级不是拍脑袋定的而是看“这个任务重复发生的频率”和“一次失误的代价”。频率越高、代价越大越值得模板化。第一优先是代码规范类。每个团队都有自己的代码规范但 AI 每次对话开始时并不知道。这类模板我通常固化在 CLAUDE.md 里比如“后端接口必须返回 Result ”“前端禁止使用 any 类型”。第二优先是固定流程类比如新增接口、修复 bug、前端组件开发。这些流程有清晰的步骤和检查点做成命令模板收益最大。第三优先是审查验证类包括代码 review、SQL 审查、依赖安全检查。这类任务需要独立视角用子代理比用普通对话效果稳定得多。提交信息模板是我特别想推荐的一个。团队协作里提交信息格式不统一是常态但 AI 完全可以帮你按规范生成。我在.claude/commands/commit-msg.md里定义了格式类型feat/fix/docs/refactor/test 影响模块 一句话描述 可选的关联 issue。每次提交前执行/commit-msgAI 会先git diff再按模板生成提交信息。这个命令看起来不起眼实际用下来团队代码历史的整洁程度提升很明显。3.3 从普通对话到正式模板的收敛路径我最初的模板并不是一次性写对的而是从零散对话里不断“提炼”出来的。这个过程可以总结为四个步骤第一步观察重复。连续一周留意自己在终端里重复输入过哪些话。如果某个需求你向 AI 描述了三遍以上这个需求就是模板候选。第二步提取稳定片段。把每次描述里固定不变的部分抽出来比如“先看 CLAUDE.md 里的结构再动手”“测试要写边界条件”。这些就是模板的骨架。第三步参数化。把每次变化的部分抽象成参数。比如写接口这个命令变化的只有路径、方法、说明其余都是固定的。用{argument-0}这类占位符代替变化内容。第四步验证并沉淀。把新模板在真实任务里跑几次发现 AI 理解偏差就立刻修改模板直到连续几次输出稳定。验证通过之后再同步到模板仓库。这套收敛路径的价值在于模板不是凭想象设计的而是从真实需求里长出来的。很多时候你以为自己需要的模板实际用了两次才发现方向不对。靠观察和提炼能让每一条模板都有实际的使用场景支撑。4. 模板的编排思路规则、命令、代理三者如何配合4.1 一个复杂任务的模板编排示例单独的模板解决单点问题但真实开发中的复杂任务往往需要多个模板配合。我拿一次“新增数据库表 对应接口 单元测试”的完整任务来展示编排思路。这个任务如果直接丢给 AI它容易漏掉某个环节或者顺序颠倒。但用模板编排之后效果稳定得多。第一步CLAUDE.md 提供背景知识。AI 在任务开始时自动读取项目结构、代码规范和表命名约定。第二步子代理完成前置审查。我调用sql-checker先审查新增表的 SQL 脚本确认字段命名、索引设计和外键关系没有问题。第三步通过/add-api命令生成接口这一步走的是常规的 controller-service-dao 流程。第四步再调用backend-reviewer子代理对生成的代码做终审检查事务、注释、返回结构。四次调用之间不是割裂的而是顺着流程推进。每次 AI 都会带着前面步骤产出的结果继续工作。实际操作中我发现这种编排方式的最大优势是每一步都有明确的责任边界。SQL 审查看的是脚本本身代码审查看的是 Java 代码不会出现“代码写得爽了数据库事务边界没人管”的情况。4.2 内容归属划分什么放规则、什么放命令、什么放代理模板多了以后最常遇到的问题就是内容放错地方。同一个信息放在 CLAUDE.md、命令模板、子代理文件三个地方效果完全不同。我发现很多人模板没起效根源就是信息放错了位置。简单总结我的划分原则状态类信息放 CLAUDE.md包括项目背景、规范、结构因为它是每次会话都需要的动作类信息放命令模板比如新增接口、执行检查因为它是按需触发的角色类信息放子代理比如架构师视角、安全视角因为它需要独立上下文。技能放那些既需要动作又需要知识库的复杂流程。举一个实际的错误案例。有一次我把“不要使用 System.out 输出”写进了某个命令模板里结果只有执行这个命令时 AI 才遵守。后来我把它移到 CLAUDE.md问题立刻消失。因为命令模板只在触发时加载而 CLAUDE.md 是每次都加载的。这个认知偏差是模板体系里最常见的坑没有之一。4.3 用钩子hooks把模板变成自动执行的流程模板不只能手动触发Claude Code 的钩子系统还能让它在特定事件发生时自动执行。我理解它就像 Git 的 hook可以在会话开始前、用户提交输入前、AI 生成内容后等时机触发脚本或指令。把钩子和模板结合能实现很多自动化的动作减少反复叮嘱。我在项目里配置过一个很实用的钩子每次会话开始时执行一个脚本检查当前分支和未提交文件数把结果作为上下文注入 AI。这样 AI 一开始就知道当前在哪个分支工作、有哪些改动还没提交不会再出现“它不知道我改了什么”的尴尬。钩子的配置内容是 YAML 格式我简化的配置大致如下hooks: SessionStart: - exec: .claude/hooks/branch-context.sh脚本输出的信息会被 Claude Code 自动作为上下文的一部分。这类钩子适合做环境探测、构建检查、日志采集把机械的动作交给脚本把决策和生成留给 AI。和模板配合起来整个工作流就从“手动输入提示词”升级成了“半自动流水线”。我在实际配置中的经验是钩子越短越好只在会话边界做一次性动作不要在钩子里写复杂业务逻辑否则排错会非常痛苦。5. 实际使用中的踩坑记录与排查技巧5.1 模板不生效先查作用域和加载顺序模板体系里最让人头疼的问题就是“我明明写了文件AI 却像没看见”。我排查这个问题时第一步永远先确认文件路径。命令模板必须放在.claude/commands/下代理模板必须放在.claude/agents/下技能必须包含SKILL.mdCLAUDE.md 必须在项目根目录或者用户主目录。路径错了内容写得再好也白搭。第二步是检查作用域覆盖。Claude Code 的配置和模板支持全局与项目两级项目级会覆盖全局级。如果全局命令和项目命令同名项目版本优先。有时候 AI 表现异常是因为你的全局 CLAUDE.md 和项目 CLAUDE.md 冲突了。我的建议是全局文件只放通用的、不会和项目冲突的偏好项目特殊约定坚决放项目文件里不要为了图省事堆到全局。第三步注意命令名的冲突。斜杠命令命中是靠文件名如果你建了一个add-api.md但系统已有同名内置命令行为可能不符合预期。这种情况我会先换一个更具体的名字比如order-add-api.md实测中降低冲突概率。模板报错时在 Claude Code 里可以查看详细日志定位是解析失败、加载超时还是上下文被截断了再针对处理。5.2 上下文被截断或丢失模板写得再长也没用这是另一个高频问题。CLAUDE.md、命令模板、子代理文件加起来有好几千字结果一执行复杂的多步骤任务AI 就把前面的内容忘了。原理上这是上下文窗口的限制。Claude Code 的每次会话并不是把所有内容无限期地都放在最高优先级早期内容可能被压缩或变得不重要模板的长尾细节就丢了。应对办法不是买更大的上下文而是控制单次模板的体量。我的实践标准是单个命令模板正文控制在 400-600 字CLAUDE.md 控制在 1500 字以内。超出部分拆到子代理或技能的知识文件里。因为技能文件中的参考文档是按需读取的不会一直占用主上下文。把“必须时刻记住”和“需要时再查”两类信息分开上下文压力会小很多。还有一个更隐蔽的问题模板里的信息彼此矛盾。比如 CLAUDE.md 说“返回统一使用 Result ”但命令模板里写“返回 ResponseEntity”AI 就会随机选一个执行。排查时我会定期做一致性检查重点看几个文件里对同一件事的描述是否一致。不一致的地方以项目级 CLAUDE.md 为准命令模板必须显式引用它而不是重复定义相同规则。5.3 模板泄露与过度膨胀你需要一套生成规范模板用久了有几个副作用一是命令越来越长二是维护越来越难三是有时候别人复制了你的模板却不适用。模板写得越长AI 的注意力越容易被稀释反而不如短模板效果好。我发现最理想的命令模板正文里超过一半是约束条件剩下是执行步骤。不要写“请你仔细分析这个问题然后采取合适的方式处理”这种空话它对 AI 没有增量信息。另一个严肃问题是模板知识的泄露。如果你把公司内部架构、密钥路径、内部域名写进 CLAUDE.md而这个模板仓库是不小心公开的就等于泄露了敏感信息。我的做法是内部项目模板中的敏感信息一律用占位符比如${DB_HOST}真正的值通过环境变量在本地传入。这一点在团队协作时尤其重要新成员 clone 模板后填自己的占位符既方便又安全。模板膨胀的解法是定期做一次“模板瘦身”。我每两周审视一遍所有模板把连续两周没人用的命令标记出来或删除或合并。模板不是越多越好而是越精准越好。我保留的最有价值的三条模板恰恰都是正文不超过五百字、但每句话都有约束力的。这个感悟希望你能在实际使用中自己体会到。5.4 实用技巧速查最后整理一张我自己反复用的速查表覆盖模板体系的常见问题症状可能原因排查与解决命令输入后没有反应文件名与命令不匹配检查.claude/commands/下的文件名AI 不遵守代码规范规范只写在命令里未写 CLAUDE.md把全局性规范移动到 CLAUDE.md长任务后期行为漂移上下文被压缩模板细节丢失精简主模板把知识库放到技能 files 目录子代理不知道任务背景子代理上下文隔离调用时显式传入背景或指定文件全局模板与项目模板冲突作用域覆盖未理解项目级优先全局只写通用内容模板执行结果不一致参数占位符写错核对{argument-N}序号和 frontmatter敏感信息出现在模板模板混入真实密钥改为占位符用环境变量注入AI 反复问你同一问题模板缺少对应信息把答案补进 CLAUDE.md 对应小节这张表是根据我自己多次踩坑整理出来的实际情况里症状和原因未必一一对应建议按“先查路径、再查作用域、后查内容”的顺序排查。模板体系的调试和普通代码调试不太一样它没有断点可以打只有一个观察实验循环改模板、跑一次真实任务、看输出是否偏离预期。坚持几次迭代模板质量就上来了。我个人在实际操作里的体会是模板工程不是一次性投入而是一个持续演进的系统。刚开始只需要做 CLAUDE.md 这一件事坚持两三个项目之后再逐步加入命令、代理、技能和钩子。别试图第一天就搭一个庞大的模板库先从一个能解决你当前最痛问题的模板开始用顺了再往深处走。最后分享一个小技巧把你的模板仓库路径记在全局配置里每次重装环境后一条命令就能把所有模板恢复到原来的位置。这套机制我从整理到现在用了大半年最大的收获不是效率提升了多少而是和 AI 协作时的确定性明显提高它越来越像一个懂项目、懂规范、稳定输出的同事而不是每次都要重新调教一遍的通用问答机器。