Claude Code 模板实战：用 CLAUDE.md 打造高效 AI 编程工作流

1. 为什么要折腾一套 Claude Code 模板1.1 从一次手忙脚乱聊起“claude-code-templates”在我这里不是某个开源仓库的名字而是我给自己的一整套工作方式起的外号。围绕 Claude Code 这个命令行编程助手我积累了大半年的使用经验最后发现真正决定体验上限的不是模型本身有多强而是你喂给它的那些约定文件——模板。引起我认真做模板的是一次真实的手忙脚乱。当时我接手一个中等规模的 React 项目代码按照 features 目录组织组件拆到 shared 和业务域两类测试统一用 Vitest接口层强制走一个自己封装的 fetch。听起来很常规对吧但我每开一个新会话基本都要重新把这些约定讲一遍哪个目录放组件测试文件命名要用.test.tsx还是.spec.tsxAPI 调用是否要走 hook 封装……工具确实能听懂问题是每开一个会话就得重新讲讲漏一处它给出的代码就会跑偏。那段时间我做得比较狼狈约等于每个工作日都在向一个记性很差的新同事解释同一套规范。后来我把这些约定全部写进了一份CLAUDE.md从“组件文件放features/xxx/components/下使用默认导出”到“测试命令用npm run test:watch”一条条往下列。它生效的方式非常朴素每次会话开始工具会自动把它作为背景信息读入。这个文件对我来说就是“项目交接文档”。以前是我开口说现在是它自己读。效果立竿见影同一份模型权重带模板和不带模板产出质量的差距非常明显。1.2 模板到底解决什么问题做模板这半年我总结出它最重要的四个价值点。第一上下文连续性。工具没有长期记忆每次对话都是全新开始但项目是长期存在的。模板就是项目记忆的外置存储把“我们约定过什么”固化下来避免每次重建全会话的上下文。没有模板的时候开工前十分钟通常都是在补背景知识有了模板开工前十分钟变成了看 diff。第二减少重复劳动。代码风格、目录结构、提交信息格式这些都是重复决策。如果不写进模板你每次都要口述一遍写进去之后模型默认就会遵守你只需要在分歧出现时纠正它。举个例子你只要在模板里写一句“提交信息遵循 Conventional Commits”后面它生成的 commit message 就会规规矩矩地带上feat:、fix:这些前缀。第三统一输出样式。团队里如果大家都用工具辅助开发有人有模板有人没有提交上来的代码就是两套风格。模板相当于把评审意见中最常说的“别那样写应该这样写”翻译成机器可以执行的规则减少交付后的返工沟通成本。这个价值在多人协作的项目里尤其明显。第四明确“完成”的标准。模板里写清楚什么算“任务完成”比写清楚怎么实现更重要。模型在没有验收标准的情况下很容易在功能基本跑通后就把状态标成完成而边界条件和异常分支被忽略了。模板把完成条件逐一列出它才会知道那步测试过了才算真的做完。这四个价值是 claude-code-templates 的核心动机。后面讲到模板文件怎么设计时其实都是在围绕这四个点做文章。2. 把 CLAUDE.md 当成项目说明书来设计2.1 CLAUDE.md 本质上是注入到上下文里的“交底书”我花了一段时间才摸清CLAUDE.md的机制。从使用表现上看它会出现在会话开始时的高优先级上下文中相当于给模型一个“接下来你要为这个项目负责”的设定。你写进文件里的内容模型不是每次都按原文引用而是作为必要背景参与生成。所以文件结构很重要。一开始我的CLAUDE.md像流水账什么内容都往里塞。后来发现效果不好因为模型读取背景时也需要抓重点。改成“角色说明 硬性规则 常用命令 验收要求”这种结构化排版之后至少有三个好处一是模型在开放任务里能够较快识别相关条款二是你后续更新的时候容易定位段落三是读的人比如团队里另一个成员也容易理解这套约定到底约束了什么。还有一个值得记住的优先级关系我自己的经验是项目级文件比用户级文件更优先。如果你在用户目录放了一套通用的“我习惯怎么写代码”但项目CLAUDE.md里约定了相反的做法模型最后通常会听项目的。这其实很合理因为项目的约定能被硬性约束验证——比如测试文件的命名规则lint 配置在仓库里是真实存在的。提示判断模板是否生效最直接的办法是在会话里问一句“当前项目的关键代码约定有哪些”。它如果答得出来说明文件生效了答不出来问题多半出在路径或优先级上。2.2 一份靠谱模板的四个层次我整理模板时遵循四层结构。每一层的功能不一样而且有顺序先定责任边界再给项目地图最后谈命令和验收。第一层角色与边界。开头用一段话说明模型在这个项目里是什么角色。我最常写的“你是本项目的长期维护工程师职责是修改既有代码不要重写整个项目。”第二句话通常是禁忌“不要动数据库迁移脚本不要自动升级依赖版本不要重构与本次需求无关的文件。”边界写清楚后面出错概率会小很多。角色和边界如果缺失模型会默认自己是个万能生成器经常产出“看起来很有道理但完全不属于本任务”的改动。第二层项目结构与命名约定。这里我会贴一个精简后的目录树标注每个目录的用途和出口。比如src/ features/ 业务模块按领域划分 auth/ components/ 页面级组件 hooks/ 业务 hooks api/ 接口封装统一走 src/lib/request shared/ 可复用组件不依赖业务领域 lib/ 请求、鉴权、通用工具配合命名规则“组件文件使用 PascalCase 默认导出hooks 文件使用 camelCase 具名导出utils 文件使用 kebab-case。”这些看起来细枝末节但模型产出如果不一致后续改起来很头疼。第三层命令与工具接入。直接列出常用命令最好用代码块方便模型在生成脚本时参考npm run dev # 启动 dev server npm run typecheck # 类型检查 npm run test # 全部测试 npm run lint # lint npm run validate # typecheck lint test这一层的细节是项目负责人最容易忘记更新的。一旦换了包管理器或者加了新的校验步骤模板里没同步模型就会按旧习惯执行然后你会看到它自作主张跑了一条早就不存在的命令。第四层验收标准与输出格式。这是四层里最容易被忽略但长期价值最高的一层。我通常会写新功能必须带至少一个测试覆盖正常路径和一个边界条件修改公共 API 时必须更新对应文档和变更日志提交信息遵循 Conventional Commits 规范格式为type(scope): description不通过 lint 的代码不视为完成验收标准定义了“完成”的含义。没有这层模型很可能在功能能跑通时直接停下或者在改完代码但忘了补测试时报“完成”。有了这层它的完成判断就要先和标准比对这对依赖工具提效的开发流程非常有用。2.3 模板库的目录组织很多新人会把所有约定塞进同一个文件导致CLAUDE.md越来越大最后没有人敢改模型也用不好。我更推荐把模板做成一个目录入口文件负责放全局常量和指针细节放旁边。我的目录结构长这样.claude/ ├── CLAUDE.md ├── commands/ │ ├── review.md │ ├── refactor.md │ └── docs.md └── references/ ├── testing-conventions.md ├── architecture.md └── style-guide.md入口文件只写“如果你要做代码评审先读commands/review.md如果你要修 bug先读references/bugfix-flow.md”。模型在实际会话里发现任务属于某个场景时再按指引去读取对应片段。这样每份文件都不会太长模型可以按需组合上下文整体效率比一份长文件高不少。3. 按工作流拆分模板让工具“知道”该干什么3.1 验收驱动式模板我经常遇到一个场景接到一个需求背景已经在对话里讲清楚了但工具在实现完 main path 之后直接宣告“完成”。为了解决这个问题我后来写了“验收驱动式模板”。它其实是一个场景指令核心是把任务描述和验收标准放在一起让模型先确认再动手。一个典型例子是实现用户列表分页接口时我在模板里写## 任务 实现 GET /api/users 分页查询接口 ## 验收标准 - 参数 page、pageSize、filters 做合法性校验 - 返回结构为 { items, total, page, pageSize } - 当 page 小于 1 时返回 400且有测试覆盖 - 不修改现有数据库迁移文件 ## 完成判定 满足上述验收标准、相关测试全部通过才算完成。这个模板的妙处在于把“完成”从“能编译”升级为“满足验收标准”。模型在执行过程中会频繁对照验收标准一旦发现某个边界情况没有被覆盖它会主动停下来补测试或告诉你风险而不是糊弄过去。我在实际使用里最明显的感受是带验收模板的任务补齐的边界测试数量明显更多。3.2 重构模板重构类任务让我栽过几次坑。模型最容易犯的问题是在重构时“顺手”改掉了一些行为而测试又没覆盖到那部分行为导致回归到线上才发现问题。后来我写的重构模板强制规定了四条每次只重构一个行为点重构前先建立测试基线重构后再跑一遍对比行为发生变化时立即停下向开发者说明重构结束后删除所有临时实验代码“建立测试基线”是我最看重的步骤。通常我会让模型先跑一次npm run test把通过、失败数量记录到一个临时文件里重构完成后再跑一次对比结果。如果通过数少了或者出现了本来不该出现的失败代码就要回滚。这个流程就像给车换零件之前先拍一张仪表盘的照片换完之后对比读数才能知道哪里没装对。有一次我用这个模板处理一个老模块模型按照模板先建了基线然后把一个三层嵌套的回调拍平了测试从 23 个通过变成 23 个通过没有引入任何行为变化。整个过程里模板提供的不是“怎么改”的指令而是“什么能改、什么时候必须停”的护栏。3.3 代码评审模板代码评审模板是我在团队里使用频率最高的一个。它不是用来生成代码的而是用来审查已有改动。最早的版本因为我没定义边界导致模型把一段本来还算合理的代码改得面目全非。后来我给它加了严格的操作范围只审查 diff不重写整个文件按“逻辑正确性 边界条件 性能 可读性 命名”的优先级给意见每条意见必须给修改建议不能只批评区分“必须修改”和“建议优化”问题必须指出对应测试是否覆盖这套模板把评审从“AI 觉得该怎么写”变成“基于 diff 的可执行清单”输出格式很适合直接粘贴到 PR 评论里。团队里用了一段时间后大家甚至开始习惯工具给出的“必须修改”优先处理再快速扫过“建议优化”评审效率提升了不少。3.4 文档与交付模板文档类任务的模板核心是“不要写华丽要写完整”。我要求模型在生成功能文档时至少覆盖以下信息点功能说明关键设计决策和理由使用示例参数、返回值、异常情况已知限制和后续优化方向之前没有这个模板的时候模型经常生成看起来结构清晰、实际上漏掉关键信息的文档。比如它不会专门提某个参数在什么情况下会返回空值用户照着文档做才发现不对。模板写清楚“必须包含”项之后生成的文档就基本能用了。变更日志同理我会约定格式要求每处改动对应到CHANGELOG.md里的具体版本条目。3.5 快捷指令模板Claude Code 支持把常用的提示词存成命令用/review、/refactor这种斜杠指令来调用。我建议在.claude/commands/目录下面为每个工作流建立一个 markdown 文件文件名就是指令名。需要注意命令模板只放该场景的专项指令不要把项目通用规则复制进去因为项目通用规则本来就在CLAUDE.md里。如果命令文件里又重复一遍会徒增指令冲突的风险。快捷指令最大的价值是降低“记忆负担”。我不需要每次手动输入一大段参数和验收标准敲一个/review就行。命令模板本身也适合走版本管理团队里谁想让命令更完善直接提 PR评审通过后所有人受益。4. 在团队里用模板做标准化4.1 模板是团队协作协议不是个人偏好当模板由多人共享时它就不再是个人玩具而是团队协议。我的经验是把它当成仓库里的“一等公民”模板文件纳入版本控制评审任何功能改动时涉及到的约定变更也会顺带检查。一个真实的例子我们团队规定所有新组件必须用函数组件和 hooks不使用 class 组件。最开始这只是一条口头约定新同事经常违反评审时总是反复提醒。后来我在CLAUDE.md里加了一句话“新组件一律使用函数组件优先使用 hooks禁止使用 class 组件历史代码除外。”从那以后工具生成的新组件就很少再出现 class 写法。这个例子说明模板的价值不只是工具效率还包括让团队规范真正落地。4.2 模板维护和迭代模板也会过期。项目升级了包管理器、改了目录结构或者调整 lint 规则模板如果滞后就会给出错误的指导。我的做法是每当全局性变更影响到代码规范就在改动当天同步更新.claude下对应的文件如果发现某个模板在连续几个会话里都被纠正说明它的措辞有问题需要重写而不是继续打补丁。另外尽量避免在多个项目里复制同一段模板。公用规则放到用户级的“base 模板”里项目里只写差异。如果一个规则在五个项目里被改过五次说明它应该向上提升反过来如果一个 base 规则在一个项目里总被绕过说明它对那个项目太强应该下沉到项目层去适配。模板的分层逻辑和代码的分层逻辑本质上是一样的。4.3 模板粒度和项目规模模板粒度是团队里经常被争论的话题。小项目我就放一个几十行的CLAUDE.md不搞目录和命令文件因为没有那么多复杂场景大项目才需要拆分成 commands 和 references因为一个文件写不下。别陷入“必须把模板建得非常完整”的焦虑。模板本身是沉淀产物先有内容再有结构。当你发现某个文件经常要翻到后半部分才能找到需要的规则时那才是拆分的时机。5. 常见问题与避坑实录5.1 模板不生效最常碰到的问题有三个。第一个是路径放错了项目根目录的CLAUDE.md才是默认读取位放在子目录里不会自动生效。第二个是优先级干扰用户级模板和项目级模板同时存在项目级优先级更高。如果你发现自己写的规则没生效先问模型“当前项目有哪些代码约定”看它答出来的内容里有没有你刚写的句子。第三个是格式问题模板里如果堆满杂乱符号和不明语法解析和权重都会受影响尽量用清晰的 Markdown少用花哨排版。注意模板不生效有时候是因为你改完文件但会话并没有刷新。如果确认路径和优先级都没问题建议开一个新会话再试因为很多工具是在会话开始时加载文件的。5.2 上下文被撑爆模板太长会导致上下文集被快速消耗。模型上下文窗口有上限模板占得越多留给任务背景和代码片段的空间就越小。这种情况下的典型表现是模型“变笨了”——不是模型能力下降而是上下文预算被无意义的规则占掉了。我通常把单个CLAUDE.md控制在 200 行以内超过的部分拆到按需读取的 references 里。这样既保留完整约定又不会让常规会话背负全部上下文。记住一个原则模板是让人尽快理解项目的速览不是把所有历史决策都塞进去的档案库。5.3 指令冲突当用户级模板、项目级模板、命令模板都写满了规则冲突是不可避免的。最典型的是测试框架的冲突项目里用 Vitest用户级模板里却写着“优先使用 jest”模型在两套指令里左右为难最后随机选了一个。解决办法是用更明确的措辞区分优先级在项目文件里写“本项目使用 Vitest 作为唯一测试框架与用户级配置冲突时以本文件为准”。模型需要一个断点判断权你在模板里明确写清优先级比重它自己推测可靠得多。5.4 “万能模板”陷阱很多人想做一个带大量参数的万能模板通过修改变量来适配各种项目。我试过之后发现这种模板越大不确定性就越高。一个模板里塞了十几个条件分支模型很难判断哪条适用最后产出可能完全不符合预期。推荐反过来做“少量模板 明确复用点”的架构。十个项目可以共用一份 react-ts base 模板然后每个项目再加一个几十行的差异文件。差异文件越短模板越稳。5.5 模板风格 vs 代码风格最后说一个容易被忽视的细节模板本身也有“风格”。如果你在模板里写“所有代码必须加极详细的注释”它会直接影响代码产出风格但可能不符合项目偏好。我吃过这类亏模板里强调“可读性优先”结果模型给所有复杂表达式都补了一长串注释代码看起来反而啰嗦。所以模板里定“用什么库、什么命名、什么测试框架”可以很刚性但涉及代码风格的地方应该写成“符合项目现有风格保持最小改动”给模型留一点因地制宜的空间。6. 个人心得与一点小技巧6.1 一次改写让我看到了模板的上限在模板这件事上我最大的体会是模板是“好决策的沉淀”不是“给 AI 的命令集”。我最有成就感的一次是在团队模板里加了一句“新代码必须先写测试再写实现”。仅仅这一行规范配合工具的强制约束整个仓库的测试覆盖率在一个月内提升了近十个百分点。模型没有变工具没有变变的只是默认决策的提示词。这件事让我意识到模板的真正价值不在于它能写出多惊艳的代码而在于它能把团队里那套“对的做法”固化下来让每次生成都站在同一条基准线上。6.2 给新手的入场建议最后分享一个重要的小技巧模板里不要只写“要做什么”一定要写“不要做什么”。禁忌往往比倡导更有约束力。比如“不要为了满足 linter 而给代码补无意义的注释”“不要重构与本次需求无关的代码”“当你不确定数据库字段含义时必须询问不要自行猜测”。负向指令让模型在开放任务中更谨慎因为它天生倾向于“多做”模板的边界就是帮它把多余的动作挡住。如果你刚开始接触 claude-code-templates我建议从项目里最痛的一个点开始比如测试约定、提交信息格式、目录规范。先写一个小的跑一两个星期观察它到底改变了什么然后再逐步扩展。模板不是一次成型的东西它更像一个会持续生长的记录迭代的幅度越小越容易保持干净。等你积累了几套顺手的工作流模板再回头看最初手忙脚乱的那个阶段会觉得这半小时的整理工作其实是最值回票价的一次“元编程”。