1. 模板才是Claude Code真正拉开差距的地方如果你只是把Claude Code当成一个能读代码、改文件、执行命令的终端助手那它顶多算一个聪明点的脚本执行器。真正让Claude Code从一个玩具变成生产力工具的是围绕它搭建的一套模板体系——claude-code-templates。这个项目名看起来平平无奇但它的价值在于把你在项目里反复交代的上下文、反复执行的流程、反复踩过的坑全部固化成模板让每一次会话从从零开始变成站在之前的肩膀上。经常用Claude Code的人应该都有这种感觉会话一开你花十几分钟把项目背景、技术栈、目录结构、注意事项挨个讲清楚结果干到一半上下文被冲掉又要重新解释一遍。或者你让它做个代码审查它给你来一堆这里可以优化、那里建议重构的废话就是不按你团队的规范来。这些问题的本质是Claude Code没有记忆也没有默认行为你不告诉它它就自由发挥。而模板就是给这个无状态的工具注入项目经验和团队规范的最直接手段。这篇文章适合正在实际使用Claude Code、又觉得效果没达到预期的人。我会从项目里最常见的CLAUDE.md项目记忆/规范文件、自定义Slash Command斜杠命令模板、Agent子代理模板、Skill技能包这几个维度展开讲清楚每类模板的作用原理、怎么设计、怎么和真实项目结合最后聊聊模板工程化之后容易踩的坑。整个过程偏实战不会给你堆一堆概念毕竟模板这东西写出来跑一遍比看十篇理论都管用。2. CLAUDE.md设计好了Claude Code才算懂你的项目2.1 CLAUDE.md到底在解决什么问题先说一个容易被忽视的事实Claude Code每一次启动会话对项目是一无所知的。它能读取文件、能搜索代码但在你真正下达指令之前它不知道你的项目是干什么的、代码风格是什么、测试怎么跑、部署流程是什么。你把这些问题在聊天里交代一遍确实能管一段时间但对话是有上下文长度的一旦溢出或者开启新会话一切归零。CLAUDE.md就是用来解决这个问题的项目记忆文件。它放在项目根目录下Claude Code启动时会自动加载里面写的内容会被当作项目背景知识持续注入到后续对话中。你可以把它理解成一个新员工入职时的公司手册——不用让每个项目成员每次开会都口头重复一遍手册里写清楚就行。这个文件的加载机制决定了它的内容设计逻辑它不是给人看的文档而是给模型看的初始化提示词。所以你写的时候要站在如何让一个第一次接触这个项目的AI快速进入状态的角度去写而不是站在如何让人类同事看懂的角度。2.2 三级CLAUDE.md企业级、用户级、项目级实际使用中CLAUDE.md并不是只有项目根目录这一个层级。按作用范围从大到小可以分三层企业级通过托管配置下发全公司所有开发者、所有项目都会加载。适合放公司级编码规范、安全红线、禁止使用的命令等全局约束。用户级~/.claude/CLAUDE.md你个人所有项目都会加载。适合放你自己的偏好比如默认使用GitHub Copilot风格的单行注释提交信息遵循Conventional Commits规范所有测试命令优先走pnpm。项目级./CLAUDE.md只对当前项目生效。适合放项目专属的技术栈、架构决策、目录约定、启动/测试命令、已知的坑。三层是合并生效的即企业级 用户级 项目级加在一起构成这个会话的完整项目背景。这个分层机制非常有用但大多数人根本没利用起来——要么所有东西一股脑塞进项目级CLAUDE.md要么干脆只写项目级导致个人偏好和项目规范混在一起换个项目就乱套。我的建议是用户级CLAUDE.md放稳定的个人工作流偏好项目级CLAUDE.md放易变的项目事实。判断依据很简单——这条规则换了项目还成不成立成立就往上放不成立就留在项目级。2.3 一个可以拿来改的CLAUDE.md骨架直接给一个我在多个项目里验证过的骨架结构你根据自己的项目删减即可# 项目概述 这是一个面向中小团队的在线协作白板应用核心功能包括实时画布、多人批注、音视频通话。 技术栈为 Next.js 14 (App Router) TypeScript Zustand tldraw Liveblocks。 # 常用命令 - 安装依赖pnpm install - 本地开发pnpm dev默认端口 3000 - 运行测试pnpm test仅跑单测 - 端到端测试pnpm test:e2e需要本地服务已启动 - 构建产物pnpm build产物输出到 .next/ # 架构约定 - 状态管理统一使用 Zustand禁止引入 Redux。 - 画布相关逻辑放在 src/canvas/ 下业务组件放在 src/components/ 下。 - API 路由只做数据透传业务逻辑抽到 src/services/。 - 所有异步请求必须走统一的 request 封装禁止直接 fetch。 # 代码风格要求 - 组件函数组件 hooks不使用 class 组件。 - 文件名使用 kebab-case。 - 导入顺序React → 第三方库 → 项目内部模块 → 类型声明。 - 所有 props 接口以 Props 结尾命名。 # 测试要求 - 新增业务逻辑必须补单元测试覆盖率不低于 80%。 - 测试文件与被测文件放在同一目录下命名为 xxx.test.ts。 # 注意事项与已知坑 - Liveblocks 的 RoomProvider 不能嵌套使用否则会报 already have a room 错误。 - tldraw 的 onChange 回调高频触发不要在里面直接 setState要用 debounce。 - 不要在服务端组件里 import 客户端专用库会导致 hydration 报错。注意几个细节第一每一条都是可执行指令不是温馨建议。你写禁止直接 fetch模型就知道不要直接用fetch你写建议使用request封装它可能还是倾向于自己写一个。给模型的指令要像给初级工程师的指令一样明确。第二把已知的坑写进去。这是CLAUDE.md最容易产生复利效应的部分——你踩过一次的坑模型下次就不会再踩相当于把项目的隐性知识沉淀下来了。我见过很多团队CLAUDE.md写得相当丰富技术栈、架构、规范全覆盖但唯独不写坑结果模型每次都踩进同一个坑里你每次都重复解释。第三CLAUDE.md不是越长越好。模型每次会话都要把完整内容加载进来太长会稀释有效信息的密度。我的经验是项目级CLAUDE.md控制在100-200行是一个比较均衡的范围超过300行就该考虑是不是把不相关的内容拆到子文件里了。3. 自定义Slash Command模板把重复操作压缩成一句话3.1 命令模板的文件形态和执行逻辑CLAUDE.md解决的是项目背景问题而自定义Slash Command解决的是高频操作问题。你在项目里做代码审查、写提交信息、生成API文档、跑规范检查——这些流程每次都要用大段提示词去描述但本质上它们是可以固化成固定模式的。Claude Code的Slash Command其实就是放在特定目录下的Markdown文件你输入斜杠命令时它会读取这个文件的内容把它作为一段额外的系统提示词注入当前对话。文件默认放在两个位置用户级目录 ~/.claude/commands/项目级目录 .claude/commands/。两者都支持子目录比如 .claude/commands/review/frontend.md命令名会带上子目录前缀。文件最前面用YAML frontmatter声明命令的元信息--- description: 执行代码审查并输出问题清单 argument-hint: [可选] 指定审查范围如 src/utils/ allowed-tools: Bash, Read, Grep, Glob ---这里的 description 是必填项Claude Code会在你输入斜杠时用模糊匹配找到对应的命令所以描述写清楚这个命令干什么比什么都重要。argument-hint让你可以接收参数。allowed-tools做工具白名单防止这个命令带着模型乱跑。3.2 参数传递$ARGUMENTS 和 位置参数命令模板的正文里可以用两个特殊变量接收用户输入的参数$ARGUMENTS 接收全部参数原始字符串$1、$2 接收按空格切分的位置参数。举个实际例子我在 .claude/commands/review.md 里写了这样一个模板--- description: 按团队规范对指定代码范围做审查 argument-hint: 文件或目录路径 allowed-tools: Bash, Read, Grep, Glob --- 请对 $ARGUMENTS 范围内的代码执行一次代码审查要求如下 1. 发现的具体问题用列表输出标注文件路径和行号抑制代码风格建议可读性建议这类泛泛而谈的评论。 2. 按严重程度分级P0明确有bug会导致运行时错误或数据错乱、P1有潜在风险如内存泄漏、并发竞争、类型断言、P2偏离团队约定可自动修复。 3. 只关注以下方面逻辑正确性、边界条件、性能隐患、安全漏洞。 4. 不要输出修改建议的代码块只需要指出问题和定位事后再让我决定怎么改。 5. 审查结束后如果发现项目CLAUDE.md中没有覆盖的已知坑先记录在审查结果的最后单独标记为建议沉淀。为什么这样设计关键在于约束输出。默认情况下Claude Code做审查很容易变成夸夸机器人——输出一堆代码写得很清晰建议提取公共函数的废话评论没有实质价值。命令模板把输出格式、关注范围、优先级定义全部约束死模型就只能在框架内干活。实测下来带上这个模板的审查结果质量和直接帮我 review 一下代码完全是两个级别。参数方面$ARGUMENTS 适合接收一整段描述比如重点看看认证模块的并发问题$1、$2 适合接收机器可解析的参数比如 git diff 的文件列表。如果命令需要严格的两个参数用位置参数做校验也方便直接判断 $2 是否为空。3.3 命令模板的最佳实践先定义不做什么我在设计命令模板时有一个原则先定义不做什么再定义做什么。直接给模型布置任务它总会倾向于做得更多——比如你让它写测试它顺手帮你把测试框架也改了你让它修bug它顺手把旁边的代码也重构成了。Separation of concerns 在模板里要写得非常明确。举例我给一个生成提交信息的模板它是这样约束模型的--- description: 根据git diff生成符合规范的提交信息 --- 先运行 git diff --cached 获取暂存区的改动内容然后根据改动生成提交信息。 约束 - 只输出提交信息正文不要输出其他任何解释。 - 提交信息格式遵循 Conventional Commitstype(scope): subject。 - type 只允许使用feat, fix, refactor, docs, test, chore。 - 不要提交与当前改动无关的内容。模版的作用本质上是行为管理系统——你通过模板预设了模型的行动边界。这个模板里最关键的一句是只输出提交信息正文不要输出其他任何解释。没有这句模型总是会附带给你讲一遍它为什么这么写然后你就得手动把多余内容删掉。这种约定输出格式的写法可以复制到任何生成类任务上。4. Agent模板与Skill模板角色分离后的工程化实践4.1 什么样的场景适合用Agent子代理Slash Command适合按一下触发一个固定流程的场景但还有一类需求是让助手在合适的时机主动介入特定的专业角色里比如写文档时希望有一个专门的文档工程师角色负责补全注释、规范格式做数据库迁移时希望有个DBA角色给出迁移脚本和回滚方案处理安全相关任务时希望有个安全审计角色扫描依赖风险。这种需求用Agent模板来落地。Claude Code的Agent子代理定义在 .claude/agents/ 目录下也支持用户级 ~/.claude/agents/每个 .md 文件定义一个Agent角色的系统提示词和可用工具。一个Agent模板的典型写法--- name: docs-architect description: 负责生成和维护项目文档擅长提炼代码行为写入中文说明。 tools: Read, Grep, Glob, Write, Edit model: claude-sonnet-4 --- 你是项目里的文档架构师。你的职责包括 1. 阅读代码逻辑将其转化为结构清晰的中文技术文档。 2. 文档风格遵循项目的Docs风格先给结论再给示例最后给边界条件。 3. 当你发现代码行为和现有文档不一致时优先修改文档以匹配代码行为而不是反过来。 4. 不要主动修改代码只负责文档相关任务。 5. 如果文档任务不明确先列一个文档大纲让用户确认再动手写。在会话中你可以用 docs-architect 这样的方式直接引用这个Agent模型就会进入文档架构师模式不再以通用助手的身份回应。你也可以把多个Agent理解为团队里不同工种的同事一个是前端专家一个是后端架构师一个是运维你按需要把问题抛给对应的人得到的答案质量远高于让一个通用模型什么都管。4.2 Agent和Slash Command到底怎么选很多人在设计模板时容易纠结这个功能用Command实现还是用Agent实现我的判断标准很简单如果你希望用户主动触发且每次执行的都是同一个固定流程用Command。如果你希望一个角色长期参与对话、被按需唤起在不同的任务上下文里用同一种专业视角参与工作用Agent。举个对比清晰的例子。代码审查这是一个固定流程——每次都要列出问题、给严重程度、输出格式固定所以适合做Command。而你希望有一个数据库运维专家的角色在涉及索引优化、迁移脚本、锁竞争分析等场景时提供专业意见这就不该做成Command因为这不是一个固定输出流程而是一种贯穿性的专业视角。这种用Agent更自然。在同一个会话里Command和Agent还可以配合Command负责把一段任务发起出去Agent负责在任务执行过程中提供专业的视角校验。比如我有个生成数据库迁移的Command它会先读取当前schema生成迁移计划然后交由db-dba这个Agent进行审查和补全回滚方案。这种组合拳是模板工程化之后才会玩出的花样。4.3 Skill模板领域知识的可复用封装Skill技能包是另一个层面的模板。如果说CLAUDE.md是项目记忆Command是操作流程Agent是角色分工那Skill就是领域知识包——把某一类任务所需的完整方法论、步骤、示例、检查清单打包成一个模型可以按需调用的单元。Skill的载体是一个目录里面包含 SKILL.md 作为入口描述文件还可以放参考文档、示例片段、校验规则等资源。SKILL.md里会描述这个Skill解决什么问题、在什么时机使用、关键步骤是什么。模型通过描述判断什么时候应该加载这个Skill来用。举个例子你可以封装一个技术方案评审Skill里面包含评审的checklist架构合理性、性能预估、安全风险、可测试性、回滚方案、常见的架构反模式对比表、输出评审报告的格式模板。Skill的独特价值在于它不受项目限制跨项目复用。CLAUDE.md是绑定项目的但一个做技术方案评审的Skill可以在任何项目里用。你可以把它们理解为你个人方法论的可移植模块。不过要提醒一句Skill不是魔法它的价值取决于你放进去的知识质量。如果在Skill里塞一堆泛泛而谈的最佳实践那模型调用它和不调用没有区别。真正有效的Skill里面放的是带有具体判断标准的、逐步可执行的方法而不是空泛的原则。5. 模板工程化的失败模式写在填坑之后的经验教训5.1 失败模式一模板臃肿导致上下文稀释模板工程化做一段时间后最常见的失控是模板越写越长。CLAUDE.md从100行膨胀到300行Command模板从一段话变成一整篇SOPAgent的定义里塞满了各种边缘情况的处理规则。问题在于模型对上下文中的信息不是一视同仁的——离当前任务越近的信息权重越高但冗长模板里的历史包袱会稀释真正关键指令的比重。我见过一个项目的CLAUDE.md光是代码规范就写了150行结果模型每次生成的代码还是不符合规定。原因不是模型没读而是信息密度太低——150行里真正有约束力的核心指令可能只有10行其余全是描述性的废话。解决办法是给模板做减法评审定期检查每条规则问自己如果删掉这条模型的行为会不会变差。不会变差就删掉。实测下来一个80行的精简CLAUDE.md对模型行为的约束力比一个400行的冗长版本高得多。5.2 失败模式二优先级冲突时模型不知道该听谁的模板分层之后有个麻烦企业级CLAUDE.md说所有接口文档必须包含鉴权说明项目级CLAUDE.md说本项目接口文档统一用Swagger注释生成不单独写markdown文档结果模型执行时就开始精神分裂一会儿按这个来一会儿按那个来。优先级的问题Claude Code有明确的合并机制但实际运行时模型通常不会严格按层级判定冲突而更倾向于就近原则——项目级和命令模板里写的内容往往比企业级优先。这本身没问题问题是你需要在设计时就把冲突消灭掉。我的做法是在设计模板时就明确高层级模板只放所有人都要遵守的底线规则具体实现方式留给低层级模板。企业级模板说所有API必须鉴权那就不要在项目模板里说本项目不需要鉴权而是在项目模板里补充鉴权统一通过auth中间件处理开发环境可以使用mock token。把冲突转成互补模型就不容易混乱。5.3 失败模式三too much trust——模板授权过度自定义Command模板里如果写了你可以执行任意Bash命令那这个模板就等于给了模型一把没有安全锁的钥匙。Claude Code本身有权限系统但模板可以把权限放大或缩小。我建议在模板设计上做最小权限每个模板的allowed-tools只放它执行任务真正需要的工具禁止使用全局通配。比如代码审查模板只需要Read、Grep、Glob就不要给它Write和Edit权限免得它审着审着顺手改了你的代码。同理Command模板里要不要允许模型运行Bash要想清楚。很多审查类、分析类的任务根本不需要Bash权限带Bash权限的模板必须在描述里强制模型先输出要执行的命令、等用户确认后再运行。这不是保守这是给未来的自己省去一堆麻烦。5.4 模板的版本管理与持续迭代模板是代码代码就要有版本管理和变更记录。我见过太多团队——CLAUDE.md改了一版又一版但没人说得清每条规则是什么时候加的、为什么加的。等到某天模型行为突然变笨了排查半天才发现是自己在新版本里加了一条互相矛盾的规则。我的经验是把模板当成项目里的一等公民对待模板变更走PR流程跟着代码一起reviewCLAUDE.md里加更新日志小节写清每次改动的背景Command模板调整后至少用一个真实场景回归测试一遍确认输出没有被意外的规则影响。听起来麻烦但模板的每一次改动都是在改变模型的默认行为这个改变的影响范围比改一行代码代码大得多。最后顺手分享两个小技巧写模板这件事我踩过坑也吃到过甜头最后留两个实战小技巧第一个技巧是模板要随着踩坑迭代。不要指望第一次写的CLAUDE.md、Command模板就是最优解。正确做法是先用一个最小的模板跑起来在真实使用中记录模型哪里行为不符合预期然后针对性补充或修改模板规则。跑两周之后回看模板你会发现它已经长成了最初完全预想不到的样子——那才是经过实践检验的、真正属于你这个项目的模板。第二个技巧是给CLAUDE.md留一个无效规则回收站。删除的规则不要直接抹掉统一丢到一个已废弃规则区域保留历史记录。这样如果后来发现某个问题又出现了你能快速看出这条规则是不是被误删了而不是从零开始重新写一遍。Claude Code的威力不在工具本身而在你给工具配置的环境和约束。模板体系就是这套环境和约束的载体值得花时间好好经营。
Claude Code模板体系实战：CLAUDE.md、命令与Agent如何工程化
1. 模板才是Claude Code真正拉开差距的地方如果你只是把Claude Code当成一个能读代码、改文件、执行命令的终端助手那它顶多算一个聪明点的脚本执行器。真正让Claude Code从一个玩具变成生产力工具的是围绕它搭建的一套模板体系——claude-code-templates。这个项目名看起来平平无奇但它的价值在于把你在项目里反复交代的上下文、反复执行的流程、反复踩过的坑全部固化成模板让每一次会话从从零开始变成站在之前的肩膀上。经常用Claude Code的人应该都有这种感觉会话一开你花十几分钟把项目背景、技术栈、目录结构、注意事项挨个讲清楚结果干到一半上下文被冲掉又要重新解释一遍。或者你让它做个代码审查它给你来一堆这里可以优化、那里建议重构的废话就是不按你团队的规范来。这些问题的本质是Claude Code没有记忆也没有默认行为你不告诉它它就自由发挥。而模板就是给这个无状态的工具注入项目经验和团队规范的最直接手段。这篇文章适合正在实际使用Claude Code、又觉得效果没达到预期的人。我会从项目里最常见的CLAUDE.md项目记忆/规范文件、自定义Slash Command斜杠命令模板、Agent子代理模板、Skill技能包这几个维度展开讲清楚每类模板的作用原理、怎么设计、怎么和真实项目结合最后聊聊模板工程化之后容易踩的坑。整个过程偏实战不会给你堆一堆概念毕竟模板这东西写出来跑一遍比看十篇理论都管用。2. CLAUDE.md设计好了Claude Code才算懂你的项目2.1 CLAUDE.md到底在解决什么问题先说一个容易被忽视的事实Claude Code每一次启动会话对项目是一无所知的。它能读取文件、能搜索代码但在你真正下达指令之前它不知道你的项目是干什么的、代码风格是什么、测试怎么跑、部署流程是什么。你把这些问题在聊天里交代一遍确实能管一段时间但对话是有上下文长度的一旦溢出或者开启新会话一切归零。CLAUDE.md就是用来解决这个问题的项目记忆文件。它放在项目根目录下Claude Code启动时会自动加载里面写的内容会被当作项目背景知识持续注入到后续对话中。你可以把它理解成一个新员工入职时的公司手册——不用让每个项目成员每次开会都口头重复一遍手册里写清楚就行。这个文件的加载机制决定了它的内容设计逻辑它不是给人看的文档而是给模型看的初始化提示词。所以你写的时候要站在如何让一个第一次接触这个项目的AI快速进入状态的角度去写而不是站在如何让人类同事看懂的角度。2.2 三级CLAUDE.md企业级、用户级、项目级实际使用中CLAUDE.md并不是只有项目根目录这一个层级。按作用范围从大到小可以分三层企业级通过托管配置下发全公司所有开发者、所有项目都会加载。适合放公司级编码规范、安全红线、禁止使用的命令等全局约束。用户级~/.claude/CLAUDE.md你个人所有项目都会加载。适合放你自己的偏好比如默认使用GitHub Copilot风格的单行注释提交信息遵循Conventional Commits规范所有测试命令优先走pnpm。项目级./CLAUDE.md只对当前项目生效。适合放项目专属的技术栈、架构决策、目录约定、启动/测试命令、已知的坑。三层是合并生效的即企业级 用户级 项目级加在一起构成这个会话的完整项目背景。这个分层机制非常有用但大多数人根本没利用起来——要么所有东西一股脑塞进项目级CLAUDE.md要么干脆只写项目级导致个人偏好和项目规范混在一起换个项目就乱套。我的建议是用户级CLAUDE.md放稳定的个人工作流偏好项目级CLAUDE.md放易变的项目事实。判断依据很简单——这条规则换了项目还成不成立成立就往上放不成立就留在项目级。2.3 一个可以拿来改的CLAUDE.md骨架直接给一个我在多个项目里验证过的骨架结构你根据自己的项目删减即可# 项目概述 这是一个面向中小团队的在线协作白板应用核心功能包括实时画布、多人批注、音视频通话。 技术栈为 Next.js 14 (App Router) TypeScript Zustand tldraw Liveblocks。 # 常用命令 - 安装依赖pnpm install - 本地开发pnpm dev默认端口 3000 - 运行测试pnpm test仅跑单测 - 端到端测试pnpm test:e2e需要本地服务已启动 - 构建产物pnpm build产物输出到 .next/ # 架构约定 - 状态管理统一使用 Zustand禁止引入 Redux。 - 画布相关逻辑放在 src/canvas/ 下业务组件放在 src/components/ 下。 - API 路由只做数据透传业务逻辑抽到 src/services/。 - 所有异步请求必须走统一的 request 封装禁止直接 fetch。 # 代码风格要求 - 组件函数组件 hooks不使用 class 组件。 - 文件名使用 kebab-case。 - 导入顺序React → 第三方库 → 项目内部模块 → 类型声明。 - 所有 props 接口以 Props 结尾命名。 # 测试要求 - 新增业务逻辑必须补单元测试覆盖率不低于 80%。 - 测试文件与被测文件放在同一目录下命名为 xxx.test.ts。 # 注意事项与已知坑 - Liveblocks 的 RoomProvider 不能嵌套使用否则会报 already have a room 错误。 - tldraw 的 onChange 回调高频触发不要在里面直接 setState要用 debounce。 - 不要在服务端组件里 import 客户端专用库会导致 hydration 报错。注意几个细节第一每一条都是可执行指令不是温馨建议。你写禁止直接 fetch模型就知道不要直接用fetch你写建议使用request封装它可能还是倾向于自己写一个。给模型的指令要像给初级工程师的指令一样明确。第二把已知的坑写进去。这是CLAUDE.md最容易产生复利效应的部分——你踩过一次的坑模型下次就不会再踩相当于把项目的隐性知识沉淀下来了。我见过很多团队CLAUDE.md写得相当丰富技术栈、架构、规范全覆盖但唯独不写坑结果模型每次都踩进同一个坑里你每次都重复解释。第三CLAUDE.md不是越长越好。模型每次会话都要把完整内容加载进来太长会稀释有效信息的密度。我的经验是项目级CLAUDE.md控制在100-200行是一个比较均衡的范围超过300行就该考虑是不是把不相关的内容拆到子文件里了。3. 自定义Slash Command模板把重复操作压缩成一句话3.1 命令模板的文件形态和执行逻辑CLAUDE.md解决的是项目背景问题而自定义Slash Command解决的是高频操作问题。你在项目里做代码审查、写提交信息、生成API文档、跑规范检查——这些流程每次都要用大段提示词去描述但本质上它们是可以固化成固定模式的。Claude Code的Slash Command其实就是放在特定目录下的Markdown文件你输入斜杠命令时它会读取这个文件的内容把它作为一段额外的系统提示词注入当前对话。文件默认放在两个位置用户级目录 ~/.claude/commands/项目级目录 .claude/commands/。两者都支持子目录比如 .claude/commands/review/frontend.md命令名会带上子目录前缀。文件最前面用YAML frontmatter声明命令的元信息--- description: 执行代码审查并输出问题清单 argument-hint: [可选] 指定审查范围如 src/utils/ allowed-tools: Bash, Read, Grep, Glob ---这里的 description 是必填项Claude Code会在你输入斜杠时用模糊匹配找到对应的命令所以描述写清楚这个命令干什么比什么都重要。argument-hint让你可以接收参数。allowed-tools做工具白名单防止这个命令带着模型乱跑。3.2 参数传递$ARGUMENTS 和 位置参数命令模板的正文里可以用两个特殊变量接收用户输入的参数$ARGUMENTS 接收全部参数原始字符串$1、$2 接收按空格切分的位置参数。举个实际例子我在 .claude/commands/review.md 里写了这样一个模板--- description: 按团队规范对指定代码范围做审查 argument-hint: 文件或目录路径 allowed-tools: Bash, Read, Grep, Glob --- 请对 $ARGUMENTS 范围内的代码执行一次代码审查要求如下 1. 发现的具体问题用列表输出标注文件路径和行号抑制代码风格建议可读性建议这类泛泛而谈的评论。 2. 按严重程度分级P0明确有bug会导致运行时错误或数据错乱、P1有潜在风险如内存泄漏、并发竞争、类型断言、P2偏离团队约定可自动修复。 3. 只关注以下方面逻辑正确性、边界条件、性能隐患、安全漏洞。 4. 不要输出修改建议的代码块只需要指出问题和定位事后再让我决定怎么改。 5. 审查结束后如果发现项目CLAUDE.md中没有覆盖的已知坑先记录在审查结果的最后单独标记为建议沉淀。为什么这样设计关键在于约束输出。默认情况下Claude Code做审查很容易变成夸夸机器人——输出一堆代码写得很清晰建议提取公共函数的废话评论没有实质价值。命令模板把输出格式、关注范围、优先级定义全部约束死模型就只能在框架内干活。实测下来带上这个模板的审查结果质量和直接帮我 review 一下代码完全是两个级别。参数方面$ARGUMENTS 适合接收一整段描述比如重点看看认证模块的并发问题$1、$2 适合接收机器可解析的参数比如 git diff 的文件列表。如果命令需要严格的两个参数用位置参数做校验也方便直接判断 $2 是否为空。3.3 命令模板的最佳实践先定义不做什么我在设计命令模板时有一个原则先定义不做什么再定义做什么。直接给模型布置任务它总会倾向于做得更多——比如你让它写测试它顺手帮你把测试框架也改了你让它修bug它顺手把旁边的代码也重构成了。Separation of concerns 在模板里要写得非常明确。举例我给一个生成提交信息的模板它是这样约束模型的--- description: 根据git diff生成符合规范的提交信息 --- 先运行 git diff --cached 获取暂存区的改动内容然后根据改动生成提交信息。 约束 - 只输出提交信息正文不要输出其他任何解释。 - 提交信息格式遵循 Conventional Commitstype(scope): subject。 - type 只允许使用feat, fix, refactor, docs, test, chore。 - 不要提交与当前改动无关的内容。模版的作用本质上是行为管理系统——你通过模板预设了模型的行动边界。这个模板里最关键的一句是只输出提交信息正文不要输出其他任何解释。没有这句模型总是会附带给你讲一遍它为什么这么写然后你就得手动把多余内容删掉。这种约定输出格式的写法可以复制到任何生成类任务上。4. Agent模板与Skill模板角色分离后的工程化实践4.1 什么样的场景适合用Agent子代理Slash Command适合按一下触发一个固定流程的场景但还有一类需求是让助手在合适的时机主动介入特定的专业角色里比如写文档时希望有一个专门的文档工程师角色负责补全注释、规范格式做数据库迁移时希望有个DBA角色给出迁移脚本和回滚方案处理安全相关任务时希望有个安全审计角色扫描依赖风险。这种需求用Agent模板来落地。Claude Code的Agent子代理定义在 .claude/agents/ 目录下也支持用户级 ~/.claude/agents/每个 .md 文件定义一个Agent角色的系统提示词和可用工具。一个Agent模板的典型写法--- name: docs-architect description: 负责生成和维护项目文档擅长提炼代码行为写入中文说明。 tools: Read, Grep, Glob, Write, Edit model: claude-sonnet-4 --- 你是项目里的文档架构师。你的职责包括 1. 阅读代码逻辑将其转化为结构清晰的中文技术文档。 2. 文档风格遵循项目的Docs风格先给结论再给示例最后给边界条件。 3. 当你发现代码行为和现有文档不一致时优先修改文档以匹配代码行为而不是反过来。 4. 不要主动修改代码只负责文档相关任务。 5. 如果文档任务不明确先列一个文档大纲让用户确认再动手写。在会话中你可以用 docs-architect 这样的方式直接引用这个Agent模型就会进入文档架构师模式不再以通用助手的身份回应。你也可以把多个Agent理解为团队里不同工种的同事一个是前端专家一个是后端架构师一个是运维你按需要把问题抛给对应的人得到的答案质量远高于让一个通用模型什么都管。4.2 Agent和Slash Command到底怎么选很多人在设计模板时容易纠结这个功能用Command实现还是用Agent实现我的判断标准很简单如果你希望用户主动触发且每次执行的都是同一个固定流程用Command。如果你希望一个角色长期参与对话、被按需唤起在不同的任务上下文里用同一种专业视角参与工作用Agent。举个对比清晰的例子。代码审查这是一个固定流程——每次都要列出问题、给严重程度、输出格式固定所以适合做Command。而你希望有一个数据库运维专家的角色在涉及索引优化、迁移脚本、锁竞争分析等场景时提供专业意见这就不该做成Command因为这不是一个固定输出流程而是一种贯穿性的专业视角。这种用Agent更自然。在同一个会话里Command和Agent还可以配合Command负责把一段任务发起出去Agent负责在任务执行过程中提供专业的视角校验。比如我有个生成数据库迁移的Command它会先读取当前schema生成迁移计划然后交由db-dba这个Agent进行审查和补全回滚方案。这种组合拳是模板工程化之后才会玩出的花样。4.3 Skill模板领域知识的可复用封装Skill技能包是另一个层面的模板。如果说CLAUDE.md是项目记忆Command是操作流程Agent是角色分工那Skill就是领域知识包——把某一类任务所需的完整方法论、步骤、示例、检查清单打包成一个模型可以按需调用的单元。Skill的载体是一个目录里面包含 SKILL.md 作为入口描述文件还可以放参考文档、示例片段、校验规则等资源。SKILL.md里会描述这个Skill解决什么问题、在什么时机使用、关键步骤是什么。模型通过描述判断什么时候应该加载这个Skill来用。举个例子你可以封装一个技术方案评审Skill里面包含评审的checklist架构合理性、性能预估、安全风险、可测试性、回滚方案、常见的架构反模式对比表、输出评审报告的格式模板。Skill的独特价值在于它不受项目限制跨项目复用。CLAUDE.md是绑定项目的但一个做技术方案评审的Skill可以在任何项目里用。你可以把它们理解为你个人方法论的可移植模块。不过要提醒一句Skill不是魔法它的价值取决于你放进去的知识质量。如果在Skill里塞一堆泛泛而谈的最佳实践那模型调用它和不调用没有区别。真正有效的Skill里面放的是带有具体判断标准的、逐步可执行的方法而不是空泛的原则。5. 模板工程化的失败模式写在填坑之后的经验教训5.1 失败模式一模板臃肿导致上下文稀释模板工程化做一段时间后最常见的失控是模板越写越长。CLAUDE.md从100行膨胀到300行Command模板从一段话变成一整篇SOPAgent的定义里塞满了各种边缘情况的处理规则。问题在于模型对上下文中的信息不是一视同仁的——离当前任务越近的信息权重越高但冗长模板里的历史包袱会稀释真正关键指令的比重。我见过一个项目的CLAUDE.md光是代码规范就写了150行结果模型每次生成的代码还是不符合规定。原因不是模型没读而是信息密度太低——150行里真正有约束力的核心指令可能只有10行其余全是描述性的废话。解决办法是给模板做减法评审定期检查每条规则问自己如果删掉这条模型的行为会不会变差。不会变差就删掉。实测下来一个80行的精简CLAUDE.md对模型行为的约束力比一个400行的冗长版本高得多。5.2 失败模式二优先级冲突时模型不知道该听谁的模板分层之后有个麻烦企业级CLAUDE.md说所有接口文档必须包含鉴权说明项目级CLAUDE.md说本项目接口文档统一用Swagger注释生成不单独写markdown文档结果模型执行时就开始精神分裂一会儿按这个来一会儿按那个来。优先级的问题Claude Code有明确的合并机制但实际运行时模型通常不会严格按层级判定冲突而更倾向于就近原则——项目级和命令模板里写的内容往往比企业级优先。这本身没问题问题是你需要在设计时就把冲突消灭掉。我的做法是在设计模板时就明确高层级模板只放所有人都要遵守的底线规则具体实现方式留给低层级模板。企业级模板说所有API必须鉴权那就不要在项目模板里说本项目不需要鉴权而是在项目模板里补充鉴权统一通过auth中间件处理开发环境可以使用mock token。把冲突转成互补模型就不容易混乱。5.3 失败模式三too much trust——模板授权过度自定义Command模板里如果写了你可以执行任意Bash命令那这个模板就等于给了模型一把没有安全锁的钥匙。Claude Code本身有权限系统但模板可以把权限放大或缩小。我建议在模板设计上做最小权限每个模板的allowed-tools只放它执行任务真正需要的工具禁止使用全局通配。比如代码审查模板只需要Read、Grep、Glob就不要给它Write和Edit权限免得它审着审着顺手改了你的代码。同理Command模板里要不要允许模型运行Bash要想清楚。很多审查类、分析类的任务根本不需要Bash权限带Bash权限的模板必须在描述里强制模型先输出要执行的命令、等用户确认后再运行。这不是保守这是给未来的自己省去一堆麻烦。5.4 模板的版本管理与持续迭代模板是代码代码就要有版本管理和变更记录。我见过太多团队——CLAUDE.md改了一版又一版但没人说得清每条规则是什么时候加的、为什么加的。等到某天模型行为突然变笨了排查半天才发现是自己在新版本里加了一条互相矛盾的规则。我的经验是把模板当成项目里的一等公民对待模板变更走PR流程跟着代码一起reviewCLAUDE.md里加更新日志小节写清每次改动的背景Command模板调整后至少用一个真实场景回归测试一遍确认输出没有被意外的规则影响。听起来麻烦但模板的每一次改动都是在改变模型的默认行为这个改变的影响范围比改一行代码代码大得多。最后顺手分享两个小技巧写模板这件事我踩过坑也吃到过甜头最后留两个实战小技巧第一个技巧是模板要随着踩坑迭代。不要指望第一次写的CLAUDE.md、Command模板就是最优解。正确做法是先用一个最小的模板跑起来在真实使用中记录模型哪里行为不符合预期然后针对性补充或修改模板规则。跑两周之后回看模板你会发现它已经长成了最初完全预想不到的样子——那才是经过实践检验的、真正属于你这个项目的模板。第二个技巧是给CLAUDE.md留一个无效规则回收站。删除的规则不要直接抹掉统一丢到一个已废弃规则区域保留历史记录。这样如果后来发现某个问题又出现了你能快速看出这条规则是不是被误删了而不是从零开始重新写一遍。Claude Code的威力不在工具本身而在你给工具配置的环境和约束。模板体系就是这套环境和约束的载体值得花时间好好经营。
