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项目人格、全局约定、代码风格每次会话启动自动加载技术栈、目录结构、编码规范、常用命令slash command高频任务的操作流程手动触发按需调用代码审查流程、提交规范、测试生成步骤memory跨会话的事实沉淀按需写入持续累积历史决策、踩坑记录、第三方库兼容性我在自己的项目里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 testvitest - 检查类型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空指针、越界、并发风险、异常吞噬 - 安全问题参数未校验、敏感数据未脱敏、注入风险 - 性能问题不必要的重复计算、N1 查询、大对象重复渲染 - 代码异味过长函数、重复代码、命名误导 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-datatemplates/commands/共享 slash commandscripts/install.sh自动把模板复制到目标位置每次有同事踩了一个新坑并沉淀出一条新规则就提一个 PR。这样模板库会逐渐变成团队的“集体经验库”而不只是某一个人的备忘录。一个注意点是全局模板的更新要谨慎项目模板的更新可以激进。全局模板一改所有项目全部受影响适合低频、稳重的更新项目模板则只要对当前项目有利随时都可以改。最后再分享一个我自己很受益的习惯定期做“模板复盘”。我会每隔一两周翻一遍 CLAUDE.md 和 slash command删掉那些“写了但从来没触发过作用”的条目。模板不是写得多就好而是每条都能在关键时刻帮你省时间这才是有价值的模板。