Claude Code 模板实战：从 CLAUDE.md 到 slash command 的工作流优化指南

1. 从“一问一答”到“模板驱动”：Claude Code 工作流的转折点

先说个我自己的经历。最早用 Claude Code 的时候，我的用法和大部分人一样：在终端里打开会话，把项目背景、代码结构、当前需求一股脑粘进去，然后等它输出。看起来没什么问题，但用久了会发现一个很尴尬的现象——每次会话的前十几分钟都是在“补背景”。

比如我今天想让它改一个支付模块的报错逻辑，我得先解释一遍我们项目的分层方式、相关的配置文件在哪、错误码体系是怎么定义的、日志怎么查。它听懂了，开始干活了。干完，会话结束。第二天换个任务，又得从头解释一遍。那种感觉就像你每天带一个新实习生，教完一遍他走了，第二天再来一个。

后来我开始研究 Claude Code 的 templates 机制，才意识到问题的本质：不是 Claude Code 不够聪明，而是我从来没有给它一套稳定的“工作上下文”。CLAUDE.md、自定义 slash command、记忆文件，这些不是花哨功能，而是把“每次都要重新解释的事”变成“一次配置、处处复用”的基础设施。

这篇文章不聊官方文档里已经写清楚的部分，重点讲我自己从零搭建一套 claude-code-templates 的经验：指令文件怎么写、slash command 怎么配、多项目怎么复用、以及我踩过的那些坑。

1.1 我最初的使用状态：为什么总感觉它在“装笨”

用 Claude Code 干活，本质上是和它共享一个工作上下文。这个上下文包括三样东西：项目背景、代码约定、任务目标。如果这三样只靠每次对话临时输入，那模型表现得再好，也有一大半算力浪费在“重新理解你”上面。

我最初就是这样的。一个典型的低效对话长这样：

我：看一下 src/services/payment/refund.ts 这个文件，里面有个 bug，应该是在回调处理的时候没有校验签名。 AI：好的，我来看看。这个文件引用了 xxx、yyy，我先梳理一下依赖关系…… 我：对，然后我们项目的签名校验逻辑一般在 utils/crypto 里，你可以参考 verifySignature 那个函数。 AI：明白了，我再看一下 verifySignature 的实现……

一来一回，小半天没了。而且每次任务不同，背景也不同，根本没有积累。真正让我下决心搞模板体系的，是有一次在同一个项目里，连续三天让它写测试，前两次它都会把测试框架的选型原因重新查一遍，好像完全不记得这个项目已经在用 vitest 而不是 jest。

1.2 模板化的核心逻辑：你缺的不是模型，是上下文工程

后来我意识到一件事：Claude Code 的表现上限，很大程度上不取决于模型本身，而取决于你给它构造的上下文质量。这跟调 prompt 完全是两码事——它不是一句两句的提示词能解决的，而是要建一套持续存在、自动加载、按需调用的上下文系统。

这正是 templates 真正发挥作用的地方：

• CLAUDE.md：每次会话开场自动读入，相当于你的“项目入职手册”
• 自定义 slash command：把重复动作固化成命令，例如 /review、/test-suite、/commit，本质上是可复用的任务模板
• 记忆文件：跨会话保存项目约定、坑位信息、技术决策

我把它理解成：CLAUDE.md 解决的是“你是谁、项目什么样”，slash command 解决的是“你常干的活怎么干”，memory 解决的是“上次记住的事别忘”。三者配合起来，Claude Code 才从一个“随机实习生”变成一个“熟悉项目的老同事”。

1.3 三件套的分工：CLAUDE.md、slash command 与 memory 的关系

很多人一上来就只写一个 CLAUDE.md，把一堆内容塞进去，结果效果并不好。我的经验是，这三者各管一段，揉在一起反而混乱。

我在自己的项目里，CLAUDE.md 一般控制在 150 行以内，只写“必须知道的事”；更细节的操作流程全部拆出去用 slash command 承载；真正发生过的问题记到 memory 里。这套结构跑了一段时间之后，最大的感受是每次开新会话的“热身期”几乎消失了，它上来就知道项目用什么框架、代码放哪、命名习惯是什么、错误处理怎么做。

2. 把项目人格写进 CLAUDE.md：一套可以直接抄走的指令文件结构

CLAUDE.md 是 Claude Code 模板体系的核心入口。它支持放在项目根目录，也可以放在用户目录~/.claude/CLAUDE.md作为全局配置。我自己的建议是：全局只放通用的行为准则，项目里一定要有自己的 CLAUDE.md，否则模板永远停在“通用”层面，落不了地。

很多人的 CLAUDE.md 写得像流水账——罗列了技术栈、目录结构、然后没了。这样写不能说没用，但效果有限。因为 Claude Code 不是搜索引擎，它需要的是“在什么情况下做什么决策”的规则，而不是一份静态文档。

2.1 我常用的 CLAUDE.md 骨架（可直接复制改）

下面这个结构是我根据自己的多个项目沉淀出来的，覆盖了日常协作中最常出现的几类信息：

# CLAUDE.md ## 项目概览 - 项目定位：一句话说清楚这个项目做什么 - 当前状态：活跃开发中 / 维护模式 / 重构中 - 核心业务领域：例如支付、权限、数据分析 ## 技术栈与关键依赖 - 语言/框架：TypeScript + React 18 + Vite - 测试框架：Vitest（不要用 Jest，项目历史原因） - 状态管理：Zustand，不用 Redux - UI 组件库：项目内 src/components/ui，优先复用 ## 目录结构约定 - src/app：路由页面，禁止放业务逻辑 - src/features：业务模块，按领域划分 - src/shared：跨模块共享组件与工具函数 - src/api：接口层，统一封装 fetch ## 编码规范 - 命名：组件 PascalCase，函数/变量 camelCase，常量 UPPER_SNAKE_CASE - 样式：Tailwind，禁止在组件里写非 Tailwind 的 CSS - 错误处理：业务错误统一抛 BizError，由全局错误边界捕获 - 注释：公共函数必须有 JSDoc，私有函数视复杂度而定 - 导入顺序：第三方包 → shared → features → 相对路径 ## 常用命令 - 启动开发：npm run dev - 运行测试：npm run test（vitest） - 检查类型：npx tsc --noEmit - 构建产物：npm run build ## 约束与偏好 - 修改代码前先读相关文件，不要凭空重构 - 涉及跨模块改动时，先说明改动方案，不要闷头改 - 生成的代码必须通过项目已有 lint 规则 - 优先使用项目已有工具函数，不要重复造轮子

结构不复杂，但每一条都有用。特别要说明的是“约束与偏好”这一节，它才是让模型行为“贴项目”的关键。比如我的项目里明确写了“涉及跨模块改动时先说明方案”，这能避免它自作主张给你重构成一团。

2.2 写好项目规范的关键细节：行为约束优先于知识罗列

很多人的 CLAUDE.md 喜欢堆知识——把项目的所有名词解释、所有接口文档都塞进去。这个方向有两个问题：一是上下文窗口有限，知识太多反而稀释了重点；二是模型缺的往往不是知识，而是决策规则。

举个例子。同样一句“这个项目用 PostgreSQL”，你写成“数据库是 PostgreSQL”和写成“数据库是 PostgreSQL，所有查询必须走 repository 层，禁止在 service 里写裸 SQL”，效果天差地别。前者只是信息，后者是行为约束。

我个人的写法原则是：每条规范都要能回答“然后呢”。如果一条规范写出来，模型读完不知道该做什么改变，那这条规范就不该写。以下是我总结的几个高频规范类型：

• 优先级类：当多个规则冲突时，听谁的（例如“类型安全优先于代码简洁”）
• 边界类：哪些文件可以动、哪些不能动（例如“src/api 下的文件只在接口变更时修改”）
• 风格类：模型生成的代码要符合什么审美（例如“组件代码控制在 100 行以内，超过必须拆分”）
• 流程类：动手改代码前需要先完成什么步骤（例如“先读测试文件了解预期行为”）

2.3 用 @import 做模块化：你的 CLAUDE.md 不该无限膨胀

CLAUDE.md 容易越写越长。我今天加一条规则，明天又觉得某个历史决策要记下来，不知不觉就到了三百行。但上下文空间是有限的，而且 Claude Code 每次会话都强制读入这段内容，塞得太满就会挤占真正干活的空间。

解决办法是用@import语法做拆分。Claude Code 支持在 CLAUDE.md 里通过@路径的方式引入另一个文件，被引入的文件会作为上下文的一部分加载。比如我的常见做法：

# CLAUDE.md ## 项目概览 （略） ## 技术栈与关键依赖 （略） @project/guides/backend-rules.md @project/guides/frontend-rules.md @project/guides/api-contract.md

这样主文件保持精简，每个子文件聚焦一个主题。比如backend-rules.md只管后端行为规范，api-contract.md只记录接口定义和调用约定。需要更新的时候，只改对应的子文件就行，主文件完全不用动。

@import 的顺序是有讲究的。越靠前的内容权重越高，我会把最核心的项目人格放在主文件里，把“查一下才知道”的类目放到子文件里。如果你写过 nginx 配置，这个逻辑就很好理解。@import 引用的路径可以是相对路径，也可以指向用户全局目录下的文件，后者适合放跨项目通用的模块。

3. 自定义 slash command：把高频操作固化成一条命令

CLAUDE.md 解决的是“模型知道项目长什么样”，slash command 解决的是“模型知道你最常干的活怎么干”。这二者的区别在于：CLAUDE.md 是状态，slash command 是动作。

我用 Claude Code 两个月之后，最明显的感受是：每天真正在做的事情其实就那几类——写测试、做代码审查、规范提交信息、查错误日志。每一类都有一套固定的操作流程，我之前却不厌其烦地在每个会话里重复输入这些流程步骤，现在想想挺傻的。

3.1 目录结构与加载机制：命令文件就该这么摆

自定义 slash command 的机制很简单：在项目根目录建一个claude/commands文件夹，里面每个.md文件就是一个命令，文件名去掉后缀就是触发命令名。例如claude/commands/review.md对应/review。

项目级命令的位置是./claude/commands/，用户级命令的位置是~/.claude/commands/。二者的区别在于作用范围：项目级命令只在当前项目里生效，适合绑定特定技术栈的流程；用户级命令在所有项目里都能用，适合放通用工作流。我个人的分配思路是：

• 用户级：/commit（统一提交规范）、/explain（解释代码）、/log（分析日志）
• 项目级：/review（本项目特定的审查清单）、/add-test（按本项目测试框架生成测试）、/gen-api（按接口文档生成调用代码）

命令文件本身就是普通的 Markdown，内容就是你要让 Claude Code 执行的指令。它支持在命令里使用参数，例如/review strict可以给命令传一个额外的修饰词。

3.2 我每天都在用的几个命令实例

给你看我项目里一个/review命令的完整内容：

# 项目级代码审查命令 你是一名资深代码审查者。请对指定文件或当前改动进行严格审查。 ## 审查步骤 1. 先读取文件的完整内容，理解其功能和上下文 2. 检查是否存在以下问题： - 潜在 bug：空指针、越界、并发风险、异常吞噬 - 安全问题：参数未校验、敏感数据未脱敏、注入风险 - 性能问题：不必要的重复计算、N+1 查询、大对象重复渲染 - 代码异味：过长函数、重复代码、命名误导 3. 对发现的问题按严重程度分级： - P0：会导致崩溃、数据错误或严重安全问题 - P1：正常逻辑下可能出错，或影响可维护性 - P2：轻微问题，可后续优化 4. 输出格式： 每个问题单独成段，包含：文件位置、问题描述、为什么是问题、建议修改方式。 最后给出总体评价和修改优先级建议。 ## 项目特有审查重点（本项目专属） - 支付回调逻辑必须严格校验签名和订单状态 - 所有对外 DTO 禁止直接暴露内部实体 - 异步任务必须处理失败重试和超时

触发的时候就是/review src/services/payment/refund.ts。它不会像以前那样等我去解释“我们项目要重点看支付回调的签名校验”，而是直接按这套流程走。这就把一次原本需要反复交代的审查工作，变成了一个开箱即用的动作。

再分享一个/commit命令，这个是放在用户级的，因为我觉得提交规范应该跨项目一致：

# 生成符合 Conventional Commits 规范的提交信息 1. 使用 git diff --staged 查看当前暂存区改动，未暂存的内容先提示用户 git add 2. 总结改动类型： - feat: 新功能 - fix: 修复 bug - refactor: 重构，不改变行为 - perf: 性能优化 - chore: 构建任务、依赖更新等杂项 3. 提交信息格式： <type>(<scope>): <subject> <body（可选，说明改动动机和影响）> 4. subject 不超过 50 字符，动词开头，用祈使句 5. 如果存在破坏性变更，在 body 末尾添加 BREAKING CHANGE 说明

用了这个命令之后，我几乎没再手动敲过提交信息。它的价值不在于“规范”，而在于每次提交都会有一个客观第三者帮你审一遍暂存区的改动，经常能发现我本来想一起提交但忘记 stage 的文件。

3.3 command 里的变量与动态参数玩法

自定义命令不仅支持静态指令，还能通过参数让命令更灵活。在命令文件里，$ARGUMENTS代表斜杠命令后面跟的所有内容。比如你写一个 /summarize 命令，命令里就用$ARGUMENTS来接收用户想总结的文件路径。

实现方式很简单：

# 总结指定文件的核心逻辑 请阅读 $ARGUMENTS，用不超过 300 字总结以下内容： 1. 这个模块的核心职责 2. 主要函数/组件及其输入输出 3. 涉及的外部依赖 4. 可能的坑和注意事项

调用时直接/summarize src/features/auth/AuthContext.tsx，$ARGUMENTS 就会被替换成路径。你甚至可以传入多个参数，比如/gen-entity Order status total，命令里用$1、$2这种位置参数来提取。

这里有个小技巧：在命令文件开头用$ARGUMENTS做一次校验。比如你的 /review 命令只接受文件路径，就可以在第一行写“如果 $ARGUMENTS 为空，提示用户提供一个文件路径，并举例说明用法”。这样即使用户只敲/review，它也明白该引导用户把参数补上，而不是直接报错。

4. 多项目模板复用方案：全局指令与项目指令的层级设计

模板体系在单个项目里跑通之后，下一个问题自然就来了：我有好几个项目，难道每个项目的 CLAUDE.md 都要从零写一遍？slash command 能不能跨项目复用？

答案是可以，但有讲究。CLAUDE.md 和 slash command 都分用户级和项目级，两套并存时可以按优先级合并。Claude Code 加载时的顺序大致是：用户级设置 → 项目级设置，项目级的优先级高于用户级。合理利用这个层级，你就能做到“全局规范统一，项目细节各定”。

4.1 用户级 CLAUDE.md 存什么：通用行为准则放这里

我的用户级~/.claude/CLAUDE.md里存的全部是在任何项目里都成立的约定。随便摘几条：

# 用户级 CLAUDE.md ## 通用行为准则 - 回答问题时先确认理解，再给方案，不要跳步 - 涉及修改代码时，先给出修改计划，确认后再动手 - 不要重复造轮子，优先检查项目是否已有类似实现 - 代码方案默认考虑可测试性，大段逻辑要可单测 ## 通用编码偏好 - 平时优先写中文注释和说明，便于协作（按团队语言习惯调整） - 生成的代码必须有清晰的命名，禁止用无含义的缩写 - 错误处理必须显式，禁止静默吞异常 ## 通用命令约定 - 在不确定项目用的包管理器时，先读取 package.json 或相应配置文件 - 涉及依赖安装时，先确认是否已有 lock 文件，在对应环境下安装

这里的每一行，放到任何项目里都不会有冲突。它像“基本素质”，项目级 CLAUDE.md 则像“岗位要求”。两者叠加，才是完整的上下文。

要特别注意一点：不要把这些通用规则写进项目级 CLAUDE.md。否则你接手一个新项目时，还得复制粘贴一遍。我在早期就犯过这个错，导致每个项目的 CLAUDE.md 开头都是同一段废话，纯属浪费上下文空间。

4.2 项目级 CLAUDE.md 存什么：只放这个项目独有的信息

对应地，项目级 CLAUDE.md 就要做到“专”。只放出了这个项目就失效的信息，例如：

• 项目的业务领域和模块划分
• 特有的技术栈选型（比如别人用 REST 你用 tRPC）
• 代码目录结构和边界约定
• 项目特有的坑（比如某个第三方库在初始化时必须传一个特殊参数）
• 团队特有的代码风格要求

举个例子，我手头一个数据同步服务项目的 CLAUDE.md 里写了这样一条：“项目使用自定义的 retry 机制，不要用第三方重试库，重试策略定义在src/lib/retryPolicy.ts；所有外部 API 调用必须传入请求 ID，用于全链路追踪”。这种信息放用户级是没用的，但在项目里就是保命的。

用一句话总结我的经验：用户级 CLAUDE.md 管“怎么当一个好工程师”，项目级 CLAUDE.md 管“怎么在这个项目里当工程师”。

4.3 用 settings.json 配合模板做权限管理

再进一步，Claude Code 的~/.claude/settings.json可以配合模板做权限管理。比如有些命令会自动修改文件或者执行构建，但你不想让它每次运行都弹权限确认框。可以在 settings.json 里预设 allow 和 deny 规则。

一个典型的例子：

{ "permissions": { "allow": [ "Read", "Glob", "Bash(npm run lint)", "Bash(npm run test)" ], "deny": [ "Bash(rm -rf *)" ] } }

这样配置之后，/review命令在执行时如果只做读操作和跑测试，就不会频繁打断你；但危险的操作依然会被拦下。

我的建议是：allow 列表要给命令留下足够的操作空间，否则模板的价值就没了。比如你设置的审查命令需要运行npm run lint来验证代码风格，如果权限配置里没有允许 Bash 执行该项，每次审查都得手动确认一次，很破坏流畅度。

5. 实测中的翻车现场：模板不生效、优先级冲突、上下文膨胀

模板再好，用起来总会遇到问题。这一节把我踩过的坑都列出来，很多都是文档里不会直接告诉你的。

5.1 模板改完不生效：最常见的三个原因

有一次我改了项目里的 CLAUDE.md，加了一条“所有组件文件必须显式导出本来类型”，然后随手开个新会话测试，发现根本没生效——模型还是按旧逻辑干活。排查之后发现原因很简单：Claude Code 的上下文是最新会话开始时加载的，旧会话不会重新加载变更后的 CLAUDE.md。

如果你修改了模板文件，必须新开一个会话才能生效。这个听起来像废话，但我栽过不止一次。在长会话里改 CLAUDE.md 是不会有什么动态效果的，别浪费时间去调试一个设计上就不会加载的东西。

第二个常见原因是目录位置放错了。自定义 slash command 如果放在claude/commands而不是claude/commands，或者文件名带了不合法字符，命令会直接不出现。注意目录名是复数，少了那个s都不会被识别。

第三个原因是长度超限或语法错误。CLAUDE.md 或者命令文件如果包含嵌套的 Markdown 表格、异常缩进、残缺代码块，加载时有可能静默失败。遇到模板“没反应”的情况，先把文件内容精简一部分或者删掉明显有问题的段落再看。

5.2 指令优先级打架：项目级规则覆盖用户级规则

用户级和项目级的 CLAUDE.md 会合并加载，二者冲突时项目级优先。但如果你的写法不当，优先级的问题不会那么显然。

我遇到过的一个实际案例是：用户级 CLAUDE.md 里写“提交代码前必须在本地跑一遍测试”，项目级 CLAUDE.md 里写“由于 CI 已经覆盖测试，本地可选跑测试以节省时间”。两条规则方向相反，最后模型的行为完全看它对上下文的理解，表现不稳定。

解法其实很简单：在项目级 CLAUDE.md 里显式声明对用户级规则的覆盖。比如写“这条项目级规则优先于用户级规则：因 CI 已覆盖测试，本地允许跳过测试”。

我的习惯是，在项目级 CLAUDE.md 的顶部放一段“更优先规则”的说明，把所有和全局规则可能有冲突的点都写清楚。这样模型在合并两个上下文时，能快速判别以哪边为准。

5.3 上下文膨胀：模板写太多反而会让模型变笨

这是最反直觉的一个坑。模板是为了提供上下文，但上下文是有限的。CLAUDE.md 写太长，每次会话光读它就消耗掉大量窗口，剩下的空间就少了，模型的注意力也会被稀释。

我测试过一组数据：一个只有 50 行 CLAUDE.md 的项目，在解决同样的代码任务时，明显比一个 CLAUDE.md 有 300 行的项目更加专注。300 行那个经常在无关的规范里转圈，甚至会出现“它记得你的提交规范，但忘了你让它补全哪个函数”的情况。

我的建议是给 CLAUDE.md 设一个“上下文预算”：主文件控制在 100 行左右，拆分出去的子文件加起来也不超过 300 行。用@import拆分时，子文件的优先级低于主文件，所以在子文件里放“参考资料级”的规范，核心行为规则留在主文件里，这个思路能让模型更准确地抓住重点。

6. 更进一步的模板玩法：身份模板、语言风格与团队复用

模板体系跑顺之后，我开始琢磨一些更进阶的玩法。这个部分的内容不是必需品，但如果你已经掌握了前面几节，它们能让工作流再上一个台阶。

6.1 用 slash command 做“身份模板”，让 AI 扮演不同角色

slash command 不只是操作流程，也可以定义 AI 的身份和视角。比如我可以这样：

# 扮演一个资深前端架构师 你是一名有 10 年经验的前端架构师，对性能优化和组件设计有深入理解。 在回答问题时： 1. 优先从可维护性、可测试性、性能三个维度分析 2. 如果我的方案有明显问题，直接指出并解释原因 3. 给出的代码示例必须考虑边界情况 当前项目的技术栈和架构约定参见 CLAUDE.md。

触发/architect 帮我看看这个组件拆分合理吗，它就会用架构师视角来审问你的设计。这种“身份模板”其实也是模板，只不过模板化的对象是“思维模式”而不是“操作流程”。我甚至会为代码审查建一个“安全工程师”身份模板，专门盯注入、鉴权、敏感数据这类安全问题。

6.2 语言风格模板：让 AI 的输出习惯契合团队协作方式

如果你不是一个人用 Claude Code，而是团队共用一套模板，语言风格就很重要。有的团队希望 AI 输出代码时用中文注释，有的要求全英文提交信息，有的希望解释问题时引用具体文件、行号和代码片段。

这些都可以写进模板。我自己构建了一套“默认解释风格”模板，放在用户级 CLAUDE.md 里：

## 解释问题的默认风格 - 先给出结论，再给出理由 - 结论不超过三句话，理由用分点列出 - 每个观点尽量附带文件路径和行号作为依据 - 若问题有多种解法，对比后再给推荐 - 避免使用“可能需要”“可能原因”等模糊措辞，有疑惑时先提出问题

这套风格成立之后，Claude Code 的回答质量肉眼可见地稳定下来。因为模板不只是约束它“不做什么”，也约束它“用什么样的结构去表达”，这让它生成的内容更像一个靠谱同事写的东西，而不是一段感觉上很厉害但没法直接落地的解释。

6.3 团队共享模板库的管理方式：如何维护一套长期演进的模板

模板不是写一次就完事的。项目演进、团队规范调整、新的坑被发现，模板都要跟着更新。我们团队目前的做法是把模板库放在一个独立的仓库里，通过脚本部署到各自的~/.claude/和项目目录下。

大概的结构是这样：

• templates/global/CLAUDE.md：全局行为准则模板
• templates/project/：按项目类型分目录，比如 node-service、react-app、python-data
• templates/commands/：共享 slash command
• scripts/install.sh：自动把模板复制到目标位置

每次有同事踩了一个新坑并沉淀出一条新规则，就提一个 PR。这样模板库会逐渐变成团队的“集体经验库”，而不只是某一个人的备忘录。

一个注意点是：全局模板的更新要谨慎，项目模板的更新可以激进。全局模板一改，所有项目全部受影响，适合低频、稳重的更新；项目模板则只要对当前项目有利，随时都可以改。

最后再分享一个我自己很受益的习惯：定期做“模板复盘”。我会每隔一两周翻一遍 CLAUDE.md 和 slash command，删掉那些“写了但从来没触发过作用”的条目。模板不是写得多就好，而是每条都能在关键时刻帮你省时间，这才是有价值的模板。