1. Claude Code 模板到底是什么为什么值得认真对待先说一个可能颠覆你直觉的结论Claude Code 项目里真正拉开效率差距的往往不是模型能力本身而是你手上那套模板资产。同样一个代码库有人让 Claude 干活像开了外挂有人却觉得它不太聪明、总是返工差别十有八九出在模板建设上。claude-code-templates 这件事我一开始也没当回事。以为不就是往 CLAUDE.md 里写点风格偏好再存几个提示词吗真正在几个中大型项目里跑起来之后才明白模板做得好不好直接决定了你是在用 AI 结对编程还是在给 AI 当全职保姆。今天这篇就把我这段时间沉淀下来的模板设计思路、文件组织方式、以及实测中踩过的坑完整地拆给你看。无论你刚接触 Claude Code还是已经在日常开发里重度使用它这套方法论都可以直接抄作业。模板本质上是三样东西的集合行为说明书告诉 Claude 你的代码规范与习惯、流程编排器把多步任务固化成可复用命令、输出契约规定交付物的结构和验收标准。它不是几段提示词的堆砌而是一套围绕具体工程场景设计的可复用 AI 工作流。理解了这层后面所有技术细节才立得住。2. 模板的运转原理它是怎么指挥Claude 的很多人对模板的第一反应是不就是在对话开始前贴一大段提示词吗其实 Claude Code 的模板机制远比贴提示词复杂而且设计得相当精巧。搞懂了运转原理你才知道模板应该怎么搭。2.1 CLAUDE.md 是常驻记忆区不是一次性指令CLAUDE.md 文件最核心的特征是它会被自动加载进每一次会话的上下文里相当于 Claude 的入职培训手册。它不依赖用户手动粘贴只要你在这个目录下启动 Claude Code系统就会主动读取并纳入上下文窗口。这意味着两件事所有特定于项目的知识优先放进 CLAUDE.md而不是每次手动告诉 ClaudeCLAUDE.md 的内容会持续占用上下文空间所以它不是越详细越好而是要在信息密度和 token 消耗之间找平衡点。我在实践中的感受是一个健康的 CLAUDE.md 未必很长但它的每一句话都要能解决一个真实问题。比如你写保持代码风格一致Claude 无法执行但如果你写函数命名使用动词开头私有方法以下划线开头Claude 就能直接落到具体输出上。2.2 Slash Command 是预编程操作像 IDE 里的快捷键除了 CLAUDE.md模板的第二大核心是自定义 Slash Command。这些命令像 IDE 里的快捷键一样一旦定义好你在对话里输入/code-review就会触发一整段预置指令流。它会读取你指定的文件、按照命令里写好的步骤执行逻辑、最后按契约格式输出结果。Slash Command 与普通提示词最大的区别在于它有固定的执行框架不允许偏离。当你想让 Claude 每次做代码审查都按同一个套路走结果可复现、逻辑可约束普通提示词做不到这点但自定义命令可以。这相当于把好的工作习惯做进了工具内部。2.3 模板的加载优先级与覆盖规则Claude Code 还支持多级配置全局配置放在~/.claude/下、项目级配置放在项目根目录、子目录级配置。加载的时候是由近及远子目录的 CLAUDE.md 优先级最高其次项目根目录最后才轮到全局配置。这个优先级规则特别重要我用它做了很多有意思的事情全局放通用于所有项目的编码风格约束项目级放当前项目的架构说明子目录级放特定模块的上下文。有冲突时就近原则生效不需要反复改全局配置。这个多层覆盖机制其实是在引导你模板要分层沉淀而不是一锅乱炖。2.4 模板与版本管理的关系Claude Code 模板本质上是纯文本资产天然适合放进 Git 仓库管理。这意味着模板可以和代码一起做版本控制、做代码评审、做迭代。我见过很多团队把 CLAUDE.md 当作一次性配置文件随写随扔结果就是项目里根本没有沉淀下任何可复用的 AI 资产。真正合理的做法是把模板当成工程资产来维护和代码一起提交、一起评审、一起迭代。这样新成员 clone 仓库之后就自动获得完整的 AI 协作环境而不需要每人手动折腾半天。3. CLAUDE.md 实战骨架一份可以直接搬走的模板前面说了原理接下来上实操。下面这份骨架是我在两个实际项目里逐步打磨出来的版本。它不是最精简的但每个部分背后都有应对的实际场景。3.1 文档头部角色定义与项目定位文档开头我会写清楚两件事这个项目是什么、Claude 在其中扮演什么角色。别小看这两句它们决定 Claude 之后所有决策的基准线。例如# 项目背景 - 项目名称QuickOrder餐饮 SaaS 系统 - 技术栈TypeScript React 前端Node.js PostgreSQL 后端 - 核心业务餐厅点餐、库存管理、多门店报表 # Claude 的角色定位 - 你是一位资深的全栈工程师同时精通支付系统与数据建模 - 在给出方案时默认考虑生产环境的稳定性与可维护性 - 主动识别潜在风险不要只完成表面要求的任务这段配置看起来并不复杂但它的作用是给 Claude定调。缺了这一段Claude 的输出往往偏通用像面试答题补上之后它会非常自然地站在你团队的实际场景里去想问题。3.2 技术规范与代码风格约束技术规范建议用规则列表 示例的方式而不是长篇散文。散文写多了 Claude 的注意力反而容易稀释列表和代码示例的效率更高# 技术规范 ## 代码风格 - 前端组件使用 TypeScript React Hooks不使用 class 组件 - API 层统一使用 tRPC不直接调用 fetch 或 axios - 所有异步操作必须使用 async/await禁止裸 promise - 数据库查询必须通过 Prisma Client不得直接执行 SQL 字符串 ## 错误处理 - 业务异常使用自定义的 AppErrorHTTP 状态码和内部错误码成对出现 - 所有已知异常必须被捕获并记录日志不允许静默吞掉异常 - 用户输入校验放在服务端执行不能只依赖前端校验 ## 测试要求 - 编写新功能时同步编写单元测试与集成测试 - 测试文件与源文件同名放在 __tests__ 目录下 - Mock 数据统一放在 fixtures 目录禁止在测试代码中内联大量 mock写这个部分时最忌讳的是把现有的口头习惯照搬进去。要挑那些 Claude 无法自行推断的、你们团队真正独特的约定。比如接口一律用 tRPC这种约定除非写明否则 Claude 大概率会生成 fetch 调用这就是模板存在的意义。3.3 常用命令与工作流索引在 CLAUDE.md 里我还习惯留一个小节告诉 Claude 本仓库有哪些自定义命令可用以及它们分别适用什么场景。这个命令索引有几个好处一是 Claude 在规划行动时可以主动选择合适的命令二是你手动输入时也有一个速查表# 常用命令索引 - /review : 完整代码审查按模块输出问题清单与修改建议 - /test : 为指定文件生成单元测试 - /docs : 为指定模块生成 API 文档 - /refactor: 重构指定函数或文件并输出前后对比 - /commit : 基于暂存区改动生成规范化的提交信息3.4 架构说明与领域知识注入架构说明是模板里最能拉开价值差距的部分但也是最容易被忽视的部分。很多项目恨不得把整个 README 塞进 CLAUDE.md其实架构信息只需要注入在写代码时一定会用到的那部分比如# 系统架构要点 - 整体采用模块化单体Modular Monolith架构 - 每个业务模块内部独立分层controller → service → repository - 模块间通信通过内部事件总线禁止模块间直接调用对方的 service - 外部系统集成集中在 integrations 目录统一处理重试与超时为什么这段看起来抽象的信息反而比代码规则更重要因为 Claude 在生成代码时如果没有架构约束它在一个模块化单体项目里很可能会去跨模块直接调用这在单次编写中看起来逻辑正常但会逐渐腐蚀整个项目的边界往往要到数月后才会暴露问题。通过在模板里预置架构边界相当于从源头把这类设计隐患堵住了。3.5 交付物定义与完成标准最后也是我最看重的部分是完成的定义。写清楚什么算完成了然后输出就稳定了# 完成标准Definition of Done 1. 代码通过 TypeScript 严格检查无 any 类型 2. 新增功能包含单元测试核心业务路径包含集成测试 3. 相关文档已更新包含但不限于 README、API 文档 4. 已在本地运行完整测试套件全部通过 5. 处理了错误与异常边界日志输出完整没有这段时Claude 经常任务做完了但啥都没到位有了这段它交付的成果基本可以直接进入人工评审环节返工率大大下降。提示CLAUDE.md 各段落的权重不是固定的。如果你的项目大量涉及遗留系统改造架构边界那一段要写到最详细如果是一个快速原型项目技术规范和完成标准反而要精简因为你更看重的是迭代速度而不是工程严谨度。4. 把高频操作固化成命令Slash Command 的设计实战相比 CLAUDE.md 的静态配置自定义 Slash Command 才算真正把工作流沉淀下来。这一章我拿两个实际命令完整走一遍设计过程从目录结构、格式定义到踩坑修正你照着抄就能起步。4.1 目录结构与基本格式Slash Command 的定义方式很简单在项目根目录建一个.claude/commands/目录每个命令一个 Markdown 文件文件名就是命令名。比如.claude/commands/review.md在对话里输入/review就会触发。命令文件内容的基本格式是系统提示词加占位符。占位符形如$ARGUMENTS、$INPUT_FILE或$OUTPUT_FILE这些变量在执行时会被实际值替换。比如--- description: 对指定文件执行完整的代码审查输出结构化问题清单 argument_hint: 文件路径或模块名称 --- 你是资深代码审查专家。请严格按以下流程对 $ARGUMENTS 执行审查 1. 先通读整个文件理解业务逻辑与数据流 2. 按严重程度排序输出所有发现的问题 3. 对每个问题标注 - 问题类型架构/逻辑/性能/安全/风格 - 影响范围 - 修复建议 4. 纯文本输出不输出任何一句客套结论这个文件里 YAML 头不是可选的装饰品它里面的 description 和 argument_hint 会被 Claude 用来理解这个命令的用途也会出现在命令菜单和自动补全里所以写得越准确越好。4.2 一个更复杂的命令批量测试生成单文件命令很快就无法满足我的需求了。在某个项目里我需要给一个模块涉及的十几个文件批量生成测试。人工逐个执行/test太慢于是我把命令升级成了带脚本的逻辑块--- description: 为指定模块的全部文件批量生成单元测试 argument_hint: 模块路径 --- 你是一位测试工程师请按照以下步骤工作 1. 扫描目录 $ARGUMENTS 下的所有源文件排除 .test.ts 和 index.ts 2. 对每个文件执行 a. 分析函数签名、依赖项和关键业务分支 b. 用 vitest 编写单元测试覆盖正常路径和至少一个异常路径 c. 遵循测试命名规范describe 描述行为it 描述具体场景 3. 所有测试文件放在源文件同目录的 __tests__ 子目录下 4. 先输出清单再逐个生成文件内容 5. 全部完成后汇总测试覆盖率估算值这类命令的威力在于它在一次会话里就能替代你手把手指导 Claude 做十几件事的繁琐过程。编排逻辑被固化下来之后执行就是一条命令的事。4.3 命令之间的组合与状态传递折腾一段时间后你一定会遇到多层命令组合的场景。比如我先跑/review拿到问题清单再跑/fix去修复问题修复完了还想自动跑一遍测试看看有没有改挂。这一步如果全靠对话上下文硬撑Claude 很容易在长对话中遗忘之前修改过的文件名和具体细节。我的解决办法是定义中间产物契约。/review的输出规定为严格的 Markdown 表格包含文件名、行号、问题类型、严重程度、修复建议/fix命令则明确规定必须引用这份表格逐行核对处理状态。这样一来前一个命令的输出格式就变成了后一个命令的有效输入两个命令之间形成了数据交接。这也引出模板设计的一个通用原则好的命令不光告诉 Claude做什么还要规定输出格式因为输出格式是后续所有自动化步骤的接口。4.4 命令的权限与安全边界在命令文件里你还可以声明是否允许 Claude 自动执行破坏性操作。比如自动修复漏洞、批量替换代码这类操作建议在命令前端明确声明需要用户确认--- description: 自动修复代码中的常见问题谨慎操作 disabled: false --- 你是一位自动修复工程师。执行任务前必须 1. 列出所有将要修改的文件清单逐一说明修改原因 2. 等待用户确认后修改 begin 3. 每修改完一个文件运行一次 typecheck 确认无类型错误 4. 如遇无法确定的逻辑保留 TODO 注释并标记需人工确认这种安全边界的声明是一种有效的实践它利用命令格式主动约束了 Agent 行为的自由度避免 AI 在自动化名义下做出超出预期的修改。4.5 命令的版本管理与命名纪律命令文件多了以后维护成本会快速上涨。我给自己定了几条纪律实测有效命令名里带动词避免歧义/review而不是/code动词容易让使用者清晰感知意图不保留不再使用的旧命令一旦沉淀下来发现没什么人用就删掉保持命令库干净关键命令变更要写进 Git 提交信息里方便追溯这个命令什么时候改过、为什么改。5. 实测中的翻车现场模板设计最容易踩的四处坑没有哪套模板是一次到位的。下面这四个问题是我在真实项目里反复遇到并修正过的。写出来希望你可以直接绕开。5.1 提示词过长导致注意力稀释一开始我总想把每个命令写得事无巨细结果命令文件越来越长Claude 反而表现变差——它开始忽略一些 mid-command 的规则只记得开头和结尾的要求。这就是典型的注意力稀释。修正思路是把命令的文件按功能压缩到一个聚焦的范围坚决不在一个命令里塞十个目的。写完后默读一遍如果重点不能在两句话内概括出来这个命令多半应该拆成两个。拆开之后每个命令更短、更聚焦执行稳定性明显提升。5.2 过度规范约束扼杀了灵活性和太短相对的是太长太死。曾经我写代码审查命令时详细到每个问题的措辞都要按模板来结果 Claude 的审查变成了机械化填空几乎不再输出那些意料之外但极其关键的问题。后来我把描述格式保留但删掉了一半措辞约束输出的质量立刻回升。核心权衡是对输出结构和完整性做硬约束对表达方式和推荐内容做软引导。硬约束保证可复现性软引导保留模型的推理空间。模板不是绳索而是护栏你划定边界而不是绑定手脚。5.3 上下文满载与成本失控Claude Code 的上下文窗口虽然大但并非无限。CLAUDE.md 越长、加载的附件越多留给实际任务推理的空间就越少。我在一个大型仓库里发现项目根目录的 CLAUDE.md 洋洋洒洒写了 3000 行结果 Claude 一开始的思考速度明显变慢而且在代码生成时也开始出现上下文过载下的低质量输出。后来我把全局性的通用规范挪到全局配置把项目级配置减到只保留架构要点和关键约定文件量剪掉将近三分之二实测后面的会话速度和输出质量都回来了。数据上是这样的CLAUDE.md 控制在 200 行以内核心约束不超过 40 条Slash Command 单文件控制在 80 行以内。超过这个规模就要考虑拆配置层级或者压缩措辞。5.4 模板库没有版本管理改坏了无法回滚模板也是会改坏的。我有一次大改架构说明结果第二天 Claude 在其他任务里的行为变得非常怪异查了半天才发现是头一天修改的 CLAUDE.md 里有一处措辞歧义被模型极端解读了。如果你没有版本管理这种问题排查会异常痛苦。所以现在我把整个.claude/目录视为一等公民纳入 Git 管理。每次调整模板commit 信息里写明改动动机遇到异常表现先git diff查看最近的模板变更。这套流程很像代码出问题先查最近的提交效率极高。注意CLAUDE.md 级别的修改影响面是所有会话所以建议变更后跑一两个典型任务验证再提交到 Git。这个先验证、后提交的习惯能避开一大半模板劣化问题。6. 从个人效率工具到团队协作资产模板库的工程化沉淀模板建设的终点不是个人顺手而是团队资产化。这一章聊聊怎么把一个个人用的 CLAUDE.md 集合升级成团队可复用的 AI 工程资产库。6.1 明确模板的可评审性我在团队里推模板时遇到的最大阻力不是技术问题而是感觉这东西像玄学——每个人都能往里写规则但没人知道规则写得对不对。解决思路是把模板当成代码一样做 review。具体做法是引入模板设计评审模板。提交 CLAUDE.md 或命令文件变更时必须附带一个简短说明解决什么问题、为什么这么设计、预期的行为变化是什么。评审人不再靠感觉而是带着三个问题去审查这条规则会不会误伤正常任务它与其他规则是否冲突它的措辞是否足够精确、可执行这套流程跑起来之后团队模板的质量明显提升。因为它在人人都能提规则和规则必须有理由之间建立了一道闸门。6.2 建立模板的回归测试代码有回归测试模板其实也能有。我的做法是维护一个小的基线测试集挑出项目里几个代表性任务比如给某个工具函数补测试、重构某个模块并保持行为不变每次模板变更后都跑一遍看输出质量有没有劣化。这个测试集不用自动化得非常复杂甚至可以是一份手动检查清单。但对团队来说它的价值在于让模板变更变得可度量不再嘴上说变好了/变差了而是有一组具体任务的输出作为证据。实测之后发现这反而是最简单、最有效的团队级保障机制。6.3 模板的多项目复用与差异化解耦做模板资产库还有一个天然诉求多个项目共用一套模板但又各有差异。我后来把模板库拆成了三层基础层通用编程规范、代码风格约定、通用命令如/commit、/explain。所有项目直接引用。组织层当前团队的工程实践约定比如 CI 规则、代码评审清单、部署流程。团队内共享。项目层只有特定项目才需要的架构说明、领域知识、特殊命令。项目独有。三层之间通过 Git submodule 或者简单的复制脚本同步。基础层和组织层更新一次所有项目都能受益项目层则完全独立演化不互相阻塞。这套分层看起来很简单但它解决了一个真实的痛点以前每个项目各自为政模板库越养越重公共规则一改四处都要去同步。分层之后公共部分和项目部分天然解耦维护成本直线下降。6.4 让模板成为新人 onboarding 的一部分最后分享一个团队层面的心得模板资产库不要只服务老手还应该成为新人 onboarding 的一环。新成员拉下仓库后读一遍 CLAUDE.md跑几个 slash command能比翻半天 wiki 更快理解团队的工程约定和工具习惯。我甚至会把团队模板库整理成一份简短的AI 协作工具入门文档放在 onboarding 清单里。新人第一天装上 Claude Code 后不用从头摸黑直接就能用一套成熟的工作流干活。这一招对团队的长期价值比任何一次单独的模板优化都大。7. 把模板当作品去维护而不是当配置去堆放回头看我自己的演进路径大概可以分为三个阶段。第一个阶段把 CLAUDE.md 当记事本抓到什么写什么结果大而杂、没什么用。第二个阶段开始做命令库每条命令都精心设计效率提升明显但发现命令和命令之间缺乏协同。第三个阶段才把整个模板资产当成一个系统来考虑——有分层、有版本记录、有回归验证、有团队评审它才真正变成一个可持续进化的工程产物。如果你现在刚开始接触 claude-code-templates 这件事我的建议很直接不用一上来就铺开设计宏大架构先挑一个你每天都要做的高频任务比如代码审查、补测试、写提交信息把它固化成第一条命令。然后跑完看结果迭代你的 CLAUDE.md。等这个循环转过几轮你自然会生出一套适合自己的模板体系。这套体系的最终目标只有一个让 AI 协作变得更可控、更可复现、更省心——因为省下来的每一个小时最后都落回到你真正该关心的业务问题上。 Claude Code 模板实战：从 CLAUDE.md 到 AI 工作流工程化
1. Claude Code 模板到底是什么为什么值得认真对待先说一个可能颠覆你直觉的结论Claude Code 项目里真正拉开效率差距的往往不是模型能力本身而是你手上那套模板资产。同样一个代码库有人让 Claude 干活像开了外挂有人却觉得它不太聪明、总是返工差别十有八九出在模板建设上。claude-code-templates 这件事我一开始也没当回事。以为不就是往 CLAUDE.md 里写点风格偏好再存几个提示词吗真正在几个中大型项目里跑起来之后才明白模板做得好不好直接决定了你是在用 AI 结对编程还是在给 AI 当全职保姆。今天这篇就把我这段时间沉淀下来的模板设计思路、文件组织方式、以及实测中踩过的坑完整地拆给你看。无论你刚接触 Claude Code还是已经在日常开发里重度使用它这套方法论都可以直接抄作业。模板本质上是三样东西的集合行为说明书告诉 Claude 你的代码规范与习惯、流程编排器把多步任务固化成可复用命令、输出契约规定交付物的结构和验收标准。它不是几段提示词的堆砌而是一套围绕具体工程场景设计的可复用 AI 工作流。理解了这层后面所有技术细节才立得住。2. 模板的运转原理它是怎么指挥Claude 的很多人对模板的第一反应是不就是在对话开始前贴一大段提示词吗其实 Claude Code 的模板机制远比贴提示词复杂而且设计得相当精巧。搞懂了运转原理你才知道模板应该怎么搭。2.1 CLAUDE.md 是常驻记忆区不是一次性指令CLAUDE.md 文件最核心的特征是它会被自动加载进每一次会话的上下文里相当于 Claude 的入职培训手册。它不依赖用户手动粘贴只要你在这个目录下启动 Claude Code系统就会主动读取并纳入上下文窗口。这意味着两件事所有特定于项目的知识优先放进 CLAUDE.md而不是每次手动告诉 ClaudeCLAUDE.md 的内容会持续占用上下文空间所以它不是越详细越好而是要在信息密度和 token 消耗之间找平衡点。我在实践中的感受是一个健康的 CLAUDE.md 未必很长但它的每一句话都要能解决一个真实问题。比如你写保持代码风格一致Claude 无法执行但如果你写函数命名使用动词开头私有方法以下划线开头Claude 就能直接落到具体输出上。2.2 Slash Command 是预编程操作像 IDE 里的快捷键除了 CLAUDE.md模板的第二大核心是自定义 Slash Command。这些命令像 IDE 里的快捷键一样一旦定义好你在对话里输入/code-review就会触发一整段预置指令流。它会读取你指定的文件、按照命令里写好的步骤执行逻辑、最后按契约格式输出结果。Slash Command 与普通提示词最大的区别在于它有固定的执行框架不允许偏离。当你想让 Claude 每次做代码审查都按同一个套路走结果可复现、逻辑可约束普通提示词做不到这点但自定义命令可以。这相当于把好的工作习惯做进了工具内部。2.3 模板的加载优先级与覆盖规则Claude Code 还支持多级配置全局配置放在~/.claude/下、项目级配置放在项目根目录、子目录级配置。加载的时候是由近及远子目录的 CLAUDE.md 优先级最高其次项目根目录最后才轮到全局配置。这个优先级规则特别重要我用它做了很多有意思的事情全局放通用于所有项目的编码风格约束项目级放当前项目的架构说明子目录级放特定模块的上下文。有冲突时就近原则生效不需要反复改全局配置。这个多层覆盖机制其实是在引导你模板要分层沉淀而不是一锅乱炖。2.4 模板与版本管理的关系Claude Code 模板本质上是纯文本资产天然适合放进 Git 仓库管理。这意味着模板可以和代码一起做版本控制、做代码评审、做迭代。我见过很多团队把 CLAUDE.md 当作一次性配置文件随写随扔结果就是项目里根本没有沉淀下任何可复用的 AI 资产。真正合理的做法是把模板当成工程资产来维护和代码一起提交、一起评审、一起迭代。这样新成员 clone 仓库之后就自动获得完整的 AI 协作环境而不需要每人手动折腾半天。3. CLAUDE.md 实战骨架一份可以直接搬走的模板前面说了原理接下来上实操。下面这份骨架是我在两个实际项目里逐步打磨出来的版本。它不是最精简的但每个部分背后都有应对的实际场景。3.1 文档头部角色定义与项目定位文档开头我会写清楚两件事这个项目是什么、Claude 在其中扮演什么角色。别小看这两句它们决定 Claude 之后所有决策的基准线。例如# 项目背景 - 项目名称QuickOrder餐饮 SaaS 系统 - 技术栈TypeScript React 前端Node.js PostgreSQL 后端 - 核心业务餐厅点餐、库存管理、多门店报表 # Claude 的角色定位 - 你是一位资深的全栈工程师同时精通支付系统与数据建模 - 在给出方案时默认考虑生产环境的稳定性与可维护性 - 主动识别潜在风险不要只完成表面要求的任务这段配置看起来并不复杂但它的作用是给 Claude定调。缺了这一段Claude 的输出往往偏通用像面试答题补上之后它会非常自然地站在你团队的实际场景里去想问题。3.2 技术规范与代码风格约束技术规范建议用规则列表 示例的方式而不是长篇散文。散文写多了 Claude 的注意力反而容易稀释列表和代码示例的效率更高# 技术规范 ## 代码风格 - 前端组件使用 TypeScript React Hooks不使用 class 组件 - API 层统一使用 tRPC不直接调用 fetch 或 axios - 所有异步操作必须使用 async/await禁止裸 promise - 数据库查询必须通过 Prisma Client不得直接执行 SQL 字符串 ## 错误处理 - 业务异常使用自定义的 AppErrorHTTP 状态码和内部错误码成对出现 - 所有已知异常必须被捕获并记录日志不允许静默吞掉异常 - 用户输入校验放在服务端执行不能只依赖前端校验 ## 测试要求 - 编写新功能时同步编写单元测试与集成测试 - 测试文件与源文件同名放在 __tests__ 目录下 - Mock 数据统一放在 fixtures 目录禁止在测试代码中内联大量 mock写这个部分时最忌讳的是把现有的口头习惯照搬进去。要挑那些 Claude 无法自行推断的、你们团队真正独特的约定。比如接口一律用 tRPC这种约定除非写明否则 Claude 大概率会生成 fetch 调用这就是模板存在的意义。3.3 常用命令与工作流索引在 CLAUDE.md 里我还习惯留一个小节告诉 Claude 本仓库有哪些自定义命令可用以及它们分别适用什么场景。这个命令索引有几个好处一是 Claude 在规划行动时可以主动选择合适的命令二是你手动输入时也有一个速查表# 常用命令索引 - /review : 完整代码审查按模块输出问题清单与修改建议 - /test : 为指定文件生成单元测试 - /docs : 为指定模块生成 API 文档 - /refactor: 重构指定函数或文件并输出前后对比 - /commit : 基于暂存区改动生成规范化的提交信息3.4 架构说明与领域知识注入架构说明是模板里最能拉开价值差距的部分但也是最容易被忽视的部分。很多项目恨不得把整个 README 塞进 CLAUDE.md其实架构信息只需要注入在写代码时一定会用到的那部分比如# 系统架构要点 - 整体采用模块化单体Modular Monolith架构 - 每个业务模块内部独立分层controller → service → repository - 模块间通信通过内部事件总线禁止模块间直接调用对方的 service - 外部系统集成集中在 integrations 目录统一处理重试与超时为什么这段看起来抽象的信息反而比代码规则更重要因为 Claude 在生成代码时如果没有架构约束它在一个模块化单体项目里很可能会去跨模块直接调用这在单次编写中看起来逻辑正常但会逐渐腐蚀整个项目的边界往往要到数月后才会暴露问题。通过在模板里预置架构边界相当于从源头把这类设计隐患堵住了。3.5 交付物定义与完成标准最后也是我最看重的部分是完成的定义。写清楚什么算完成了然后输出就稳定了# 完成标准Definition of Done 1. 代码通过 TypeScript 严格检查无 any 类型 2. 新增功能包含单元测试核心业务路径包含集成测试 3. 相关文档已更新包含但不限于 README、API 文档 4. 已在本地运行完整测试套件全部通过 5. 处理了错误与异常边界日志输出完整没有这段时Claude 经常任务做完了但啥都没到位有了这段它交付的成果基本可以直接进入人工评审环节返工率大大下降。提示CLAUDE.md 各段落的权重不是固定的。如果你的项目大量涉及遗留系统改造架构边界那一段要写到最详细如果是一个快速原型项目技术规范和完成标准反而要精简因为你更看重的是迭代速度而不是工程严谨度。4. 把高频操作固化成命令Slash Command 的设计实战相比 CLAUDE.md 的静态配置自定义 Slash Command 才算真正把工作流沉淀下来。这一章我拿两个实际命令完整走一遍设计过程从目录结构、格式定义到踩坑修正你照着抄就能起步。4.1 目录结构与基本格式Slash Command 的定义方式很简单在项目根目录建一个.claude/commands/目录每个命令一个 Markdown 文件文件名就是命令名。比如.claude/commands/review.md在对话里输入/review就会触发。命令文件内容的基本格式是系统提示词加占位符。占位符形如$ARGUMENTS、$INPUT_FILE或$OUTPUT_FILE这些变量在执行时会被实际值替换。比如--- description: 对指定文件执行完整的代码审查输出结构化问题清单 argument_hint: 文件路径或模块名称 --- 你是资深代码审查专家。请严格按以下流程对 $ARGUMENTS 执行审查 1. 先通读整个文件理解业务逻辑与数据流 2. 按严重程度排序输出所有发现的问题 3. 对每个问题标注 - 问题类型架构/逻辑/性能/安全/风格 - 影响范围 - 修复建议 4. 纯文本输出不输出任何一句客套结论这个文件里 YAML 头不是可选的装饰品它里面的 description 和 argument_hint 会被 Claude 用来理解这个命令的用途也会出现在命令菜单和自动补全里所以写得越准确越好。4.2 一个更复杂的命令批量测试生成单文件命令很快就无法满足我的需求了。在某个项目里我需要给一个模块涉及的十几个文件批量生成测试。人工逐个执行/test太慢于是我把命令升级成了带脚本的逻辑块--- description: 为指定模块的全部文件批量生成单元测试 argument_hint: 模块路径 --- 你是一位测试工程师请按照以下步骤工作 1. 扫描目录 $ARGUMENTS 下的所有源文件排除 .test.ts 和 index.ts 2. 对每个文件执行 a. 分析函数签名、依赖项和关键业务分支 b. 用 vitest 编写单元测试覆盖正常路径和至少一个异常路径 c. 遵循测试命名规范describe 描述行为it 描述具体场景 3. 所有测试文件放在源文件同目录的 __tests__ 子目录下 4. 先输出清单再逐个生成文件内容 5. 全部完成后汇总测试覆盖率估算值这类命令的威力在于它在一次会话里就能替代你手把手指导 Claude 做十几件事的繁琐过程。编排逻辑被固化下来之后执行就是一条命令的事。4.3 命令之间的组合与状态传递折腾一段时间后你一定会遇到多层命令组合的场景。比如我先跑/review拿到问题清单再跑/fix去修复问题修复完了还想自动跑一遍测试看看有没有改挂。这一步如果全靠对话上下文硬撑Claude 很容易在长对话中遗忘之前修改过的文件名和具体细节。我的解决办法是定义中间产物契约。/review的输出规定为严格的 Markdown 表格包含文件名、行号、问题类型、严重程度、修复建议/fix命令则明确规定必须引用这份表格逐行核对处理状态。这样一来前一个命令的输出格式就变成了后一个命令的有效输入两个命令之间形成了数据交接。这也引出模板设计的一个通用原则好的命令不光告诉 Claude做什么还要规定输出格式因为输出格式是后续所有自动化步骤的接口。4.4 命令的权限与安全边界在命令文件里你还可以声明是否允许 Claude 自动执行破坏性操作。比如自动修复漏洞、批量替换代码这类操作建议在命令前端明确声明需要用户确认--- description: 自动修复代码中的常见问题谨慎操作 disabled: false --- 你是一位自动修复工程师。执行任务前必须 1. 列出所有将要修改的文件清单逐一说明修改原因 2. 等待用户确认后修改 begin 3. 每修改完一个文件运行一次 typecheck 确认无类型错误 4. 如遇无法确定的逻辑保留 TODO 注释并标记需人工确认这种安全边界的声明是一种有效的实践它利用命令格式主动约束了 Agent 行为的自由度避免 AI 在自动化名义下做出超出预期的修改。4.5 命令的版本管理与命名纪律命令文件多了以后维护成本会快速上涨。我给自己定了几条纪律实测有效命令名里带动词避免歧义/review而不是/code动词容易让使用者清晰感知意图不保留不再使用的旧命令一旦沉淀下来发现没什么人用就删掉保持命令库干净关键命令变更要写进 Git 提交信息里方便追溯这个命令什么时候改过、为什么改。5. 实测中的翻车现场模板设计最容易踩的四处坑没有哪套模板是一次到位的。下面这四个问题是我在真实项目里反复遇到并修正过的。写出来希望你可以直接绕开。5.1 提示词过长导致注意力稀释一开始我总想把每个命令写得事无巨细结果命令文件越来越长Claude 反而表现变差——它开始忽略一些 mid-command 的规则只记得开头和结尾的要求。这就是典型的注意力稀释。修正思路是把命令的文件按功能压缩到一个聚焦的范围坚决不在一个命令里塞十个目的。写完后默读一遍如果重点不能在两句话内概括出来这个命令多半应该拆成两个。拆开之后每个命令更短、更聚焦执行稳定性明显提升。5.2 过度规范约束扼杀了灵活性和太短相对的是太长太死。曾经我写代码审查命令时详细到每个问题的措辞都要按模板来结果 Claude 的审查变成了机械化填空几乎不再输出那些意料之外但极其关键的问题。后来我把描述格式保留但删掉了一半措辞约束输出的质量立刻回升。核心权衡是对输出结构和完整性做硬约束对表达方式和推荐内容做软引导。硬约束保证可复现性软引导保留模型的推理空间。模板不是绳索而是护栏你划定边界而不是绑定手脚。5.3 上下文满载与成本失控Claude Code 的上下文窗口虽然大但并非无限。CLAUDE.md 越长、加载的附件越多留给实际任务推理的空间就越少。我在一个大型仓库里发现项目根目录的 CLAUDE.md 洋洋洒洒写了 3000 行结果 Claude 一开始的思考速度明显变慢而且在代码生成时也开始出现上下文过载下的低质量输出。后来我把全局性的通用规范挪到全局配置把项目级配置减到只保留架构要点和关键约定文件量剪掉将近三分之二实测后面的会话速度和输出质量都回来了。数据上是这样的CLAUDE.md 控制在 200 行以内核心约束不超过 40 条Slash Command 单文件控制在 80 行以内。超过这个规模就要考虑拆配置层级或者压缩措辞。5.4 模板库没有版本管理改坏了无法回滚模板也是会改坏的。我有一次大改架构说明结果第二天 Claude 在其他任务里的行为变得非常怪异查了半天才发现是头一天修改的 CLAUDE.md 里有一处措辞歧义被模型极端解读了。如果你没有版本管理这种问题排查会异常痛苦。所以现在我把整个.claude/目录视为一等公民纳入 Git 管理。每次调整模板commit 信息里写明改动动机遇到异常表现先git diff查看最近的模板变更。这套流程很像代码出问题先查最近的提交效率极高。注意CLAUDE.md 级别的修改影响面是所有会话所以建议变更后跑一两个典型任务验证再提交到 Git。这个先验证、后提交的习惯能避开一大半模板劣化问题。6. 从个人效率工具到团队协作资产模板库的工程化沉淀模板建设的终点不是个人顺手而是团队资产化。这一章聊聊怎么把一个个人用的 CLAUDE.md 集合升级成团队可复用的 AI 工程资产库。6.1 明确模板的可评审性我在团队里推模板时遇到的最大阻力不是技术问题而是感觉这东西像玄学——每个人都能往里写规则但没人知道规则写得对不对。解决思路是把模板当成代码一样做 review。具体做法是引入模板设计评审模板。提交 CLAUDE.md 或命令文件变更时必须附带一个简短说明解决什么问题、为什么这么设计、预期的行为变化是什么。评审人不再靠感觉而是带着三个问题去审查这条规则会不会误伤正常任务它与其他规则是否冲突它的措辞是否足够精确、可执行这套流程跑起来之后团队模板的质量明显提升。因为它在人人都能提规则和规则必须有理由之间建立了一道闸门。6.2 建立模板的回归测试代码有回归测试模板其实也能有。我的做法是维护一个小的基线测试集挑出项目里几个代表性任务比如给某个工具函数补测试、重构某个模块并保持行为不变每次模板变更后都跑一遍看输出质量有没有劣化。这个测试集不用自动化得非常复杂甚至可以是一份手动检查清单。但对团队来说它的价值在于让模板变更变得可度量不再嘴上说变好了/变差了而是有一组具体任务的输出作为证据。实测之后发现这反而是最简单、最有效的团队级保障机制。6.3 模板的多项目复用与差异化解耦做模板资产库还有一个天然诉求多个项目共用一套模板但又各有差异。我后来把模板库拆成了三层基础层通用编程规范、代码风格约定、通用命令如/commit、/explain。所有项目直接引用。组织层当前团队的工程实践约定比如 CI 规则、代码评审清单、部署流程。团队内共享。项目层只有特定项目才需要的架构说明、领域知识、特殊命令。项目独有。三层之间通过 Git submodule 或者简单的复制脚本同步。基础层和组织层更新一次所有项目都能受益项目层则完全独立演化不互相阻塞。这套分层看起来很简单但它解决了一个真实的痛点以前每个项目各自为政模板库越养越重公共规则一改四处都要去同步。分层之后公共部分和项目部分天然解耦维护成本直线下降。6.4 让模板成为新人 onboarding 的一部分最后分享一个团队层面的心得模板资产库不要只服务老手还应该成为新人 onboarding 的一环。新成员拉下仓库后读一遍 CLAUDE.md跑几个 slash command能比翻半天 wiki 更快理解团队的工程约定和工具习惯。我甚至会把团队模板库整理成一份简短的AI 协作工具入门文档放在 onboarding 清单里。新人第一天装上 Claude Code 后不用从头摸黑直接就能用一套成熟的工作流干活。这一招对团队的长期价值比任何一次单独的模板优化都大。7. 把模板当作品去维护而不是当配置去堆放回头看我自己的演进路径大概可以分为三个阶段。第一个阶段把 CLAUDE.md 当记事本抓到什么写什么结果大而杂、没什么用。第二个阶段开始做命令库每条命令都精心设计效率提升明显但发现命令和命令之间缺乏协同。第三个阶段才把整个模板资产当成一个系统来考虑——有分层、有版本记录、有回归验证、有团队评审它才真正变成一个可持续进化的工程产物。如果你现在刚开始接触 claude-code-templates 这件事我的建议很直接不用一上来就铺开设计宏大架构先挑一个你每天都要做的高频任务比如代码审查、补测试、写提交信息把它固化成第一条命令。然后跑完看结果迭代你的 CLAUDE.md。等这个循环转过几轮你自然会生出一套适合自己的模板体系。这套体系的最终目标只有一个让 AI 协作变得更可控、更可复现、更省心——因为省下来的每一个小时最后都落回到你真正该关心的业务问题上。