1. 先弄清楚一件事Claude Code的“模板”到底指什么我在接触claude-code-templates这个方向之前也以为模板无非就是“把常用的代码片段存起来下次让 AI 照着写”。但真正在项目里把 Claude Code 当主力工具用了几个月之后我发现自己对“模板”的理解完全被刷新了。Claude Code 里的模板本质上分为三个层次项目记忆模板CLAUDE.md、斜杠命令模板slash commands以及输出风格模板output styles。三者解决的问题完全不同但很多人一开始只盯着代码片段模板结果用起来总觉得差点意思。先说项目记忆模板。Claude Code 每次启动时会自动读取项目根目录下的CLAUDE.md文件以及各级子目录中的 CLAUDE.md把它们作为整个会话的“背景知识”。你写不写这个文件Claude Code 的表现完全是两个样子不写的话它每轮对话都在猜测你的技术栈、项目结构、编码偏好写了之后它一上场就知道你用的是 pnpm 还是 npm、测试框架是 Vitest 还是 Jest、目录组织是 features 还是 layers、变量命名有没有特殊要求。这就是最核心的模板——它不是给 AI 看的提示词而是给项目立的规矩。再就是斜杠命令模板。你在 .claude/commands 目录下放的每一个 Markdown 文件都会变成一个/命令名比如/review、/refactor、/commit。这相当于把“你平时反复让 AI 做的事情”固化成了一套标准化操作流程。跟 CLAUDE.md 的差异在于CLAUDE.md 是静态背景知识而斜杠命令是动态操作指令可以带参数、可以指定执行步骤、可以要求输出格式。第三个是输出风格模板。很多人在做代码审查或者生成提交信息时会觉得 AI 的回答“不够对味”其实是因为你从来没给它定义过输出风格。Claude Code 的 output styles 功能就是干这个的但这个稍后我展开讲因为它是最容易被忽略、却最能提升“手感”的一层。这篇文章我主要分享的是我自己沉淀下来的整套模板体系从 CLAUDE.md 怎么写到自定义命令怎么设计再到模板怎么和真实项目保持同步。目标读者是那些已经上手了 Claude Code、但还在“临时发挥”的朋友以及正准备把 Claude Code 引入团队、想建立一套可复用规范的人。这些东西不是官方文档里抄来的概念而是我踩过一堆坑之后摸出来的实操套路。2. 项目记忆模板的设计骨架CLAUDE.md 该写什么不该写什么2.1 一套可复制的 CLAUDE.md 目录结构很多人写 CLAUDE.md 的通病是要么只写两行“这是一个 React 项目”要么写一篇三千字的长文把项目背景、编码规范、测试方案全塞进去。这两种做法都不对。写得太短AI 等于什么都不知道写得太长AI 的注意力会被稀释真正重要的约束反而记不住。我自己的做法是把 CLAUDE.md 当成一个索引文件主体内容量控制在 40 到 80 行超长的细节一律拆到独立文件里再通过相对路径引用。下面是我新建项目时默认使用的模板骨架# 项目概述 - 项目类型Next.js 14 全栈应用App Router 模式 - 核心业务面向中小团队的工时统计与排期管理 - 关键约束所有数据操作必须走服务端禁止在客户端组件里直接访问数据库 # 技术栈与命令 - 包管理器pnpm不要用 npm 或 yarn - 开发启动pnpm dev端口固定为 3000 - 类型检查pnpm typecheckTS 严格模式禁止使用 any - 测试命令pnpm testVitest React Testing Library - Lint/FormatESLint 9 Prettier # 目录结构与分层规范 - src/app路由与页面组件 - src/components跨业务共享的 UI 组件纯展示禁止写数据请求 - src/features按业务域划分的模块每个模块包含 api / components / hooks / utils - src/lib通用工具函数、与服务端交互的 client 层 - 新功能开发时优先放入对应 feature 目录禁止在 app 目录堆业务逻辑 # 编码约定 - 组件命名PascalCase文件名与组件名保持一致 - 数据请求使用 React Query缓存策略按接口幂等性判断 - 样式方案Tailwind CSS Modules 混合全局样式文件只有 globals.css - 错误处理所有 service 层函数必须返回 Result 类型禁止直接 throw 到 UI 层 # 需要特别注意的坑 - 该项目的日期处理统一用 dayjs不要往里引入 moment - 服务端环境变量只在 server 端读取不要用 NEXT_PUBLIC_ 前缀暴露密钥 - 修改数据库 schema 后必须同步生成迁移文件禁止直接改表结构注意上面这个模板里没有一句“请你写代码时遵守某某规范”的废话全部是可验证、可执行的硬约束。AI 读它的时候不需要做任何推理直接照做就行。2.2 写 CLAUDE.md 的四个关键思路第一能用命令和文件路径说清楚的绝不用形容词。比如“代码要保证高质量”就是一句毫无信息量的话而“所有 service 层函数必须返回 Result 类型”就是一条可以执行的命令。AI 不是不懂“高质量”的意思而是它不知道你的项目里“高质量”具体指什么。第二把迁移历史里踩过的坑直接写进模板。我的 CLAUDE.md 里专门有一节叫“需要特别注意的坑”凡是团队里有人犯过错、导致线上事故或者返工的点我都会沉淀进去。比如上面写的“日期处理统一用 dayjs”就是因为有人中途引了 moment导致打包体积暴增且行为不一致。这种坑写进模板后AI 后续生成代码时天然会避开。第三模板必须区分“全局约定”和“当前任务上下文”。全局约定放进 CLAUDE.md任务上下文放进你每天对话时的开场消息里。不要试图在 CLAUDE.md 里写上“今天我们要做的是登录模块”——那是临时的模板只管长期稳定的东西。第四子目录 CLAUDE.md 别当摆设。Claude Code 是支持层级目录记忆的比如src/features/billing/CLAUDE.md可以单独描述这个模块的特殊逻辑。我在中大型项目里会发现一个很明显的效果根目录 CLAUDE.md 管全局规范子目录 CLAUDE.md 管具体模块细节AI 在处理某个文件时参考的效率比那种全部塞进一个大文件里的方式高得多。3. 把高频操作固化成斜杠命令手写 commands 模板的实用思路3.1 一个 command 模板的内部结构CLAUDE.md 解决了 AI “知道上下文”的问题但每次想让 AI 干活的时候你还是得用自然语言把需求描述一遍。描述得多了你就会发现有一部分需求其实模式非常固定。比如“帮我审查一下刚刚改动的代码”“按团队规范生成一次提交信息”“把一个 callback 嵌套的旧组件改成 hooks 写法”——这些事情的操作步骤、输出格式、注意事项都是高度相似的只是具体对象在变。这就是斜杠命令模板的价值。在.claude/commands/目录下每个.md文件对应一个命令文件名就是命令名。下面是我最常用的 code review 命令模板你可以直接参考--- description: 对当前分支的改动进行代码审查聚焦高风险点 argument-hint: 可指定审查范围如只审查 src/features/billing 目录 --- 请以资深审核者身份审查最近改动。 ## 背景 项目约定见 CLAUDE.md本次重点审查 {{argument}} 指定的范围。 ## 执行步骤 1. 运行 git diff 查看改动全貌定位新增或修改文件列表 2. 检查每个文件的改动是否遵循 CLAUDE.md 中的目录结构、命名、错误处理规范 3. 重点关注以下风险点 - 数据请求是否经过 service 层是否处理了 loading / error 状态 - 新增依赖是否合理是否存在重复造轮子 - 类型安全是否出现 any、类型断言、未导出类型 - 安全是否存在用户输入直接插入 HTML、SQL 注入风险 4. 如果改动涉及数据库 schema 或 API 契约检查是否有对应的迁移/文档更新 ## 输出格式 - 按“严重问题 / 建议优化 / 风格类”三级分类列出问题 - 每个问题必须给出文件路径 行号 问题说明 具体修改建议 - 如果未发现严重问题明确写“未发现阻塞性问题”列出 2-3 个可优化点这个命令是带参数的使用时直接输入/review src/features/billing就能限定审查范围。在 Claude Code 的语法里{{argument}}就是用户输入的部分。3.2 command 模板设计的核心原则设计 command 模板时我最看重三点可预测的输出结构、明确的执行顺序、可验证的完成标准。先说输出结构。AI 生成代码审查意见时如果不给输出格式约束它会给你列个一二三四五点看起来很有条理但你仔细一看会发现很多内容是重复的比如“代码整体质量不错但部分函数可以拆分”。这种审查意见完全不可用。我的经验是输出结构越具体AI 的回答质量越稳定。所以我在模板里要求了“文件路径 行号 问题说明 修改建议”这四个要素缺一不可AI 一旦知道你要什么它就会按这个去找问题而不是泛泛而谈。执行顺序也一样。假设你在生成一个“提交信息”命令你不告诉 AI 先看 git status、再看 git diff它可能会直接从 git log 推测你的提交风格生成一个完全不符合当前变更内容的 commit message。所以命令模板里的步骤其实就是给 AI 设计的一条“工作流”跟给人设计 SOP 是一模一样的逻辑。完成标准这一点很多教程都不会提但我认为是决定命令好不好用的关键。比如 review 命令里我写了“如果未发现严重问题明确写‘未发现阻塞性问题’”。这句话看着简单实际作用是避免了 AI 为了凑字数硬挑毛病的情况——它知道没有严重问题的时候可以大大方方说没有而不是编造一堆低质量建议来显示自己很努力。4. 三个高频场景模板拆解从 API 后端到前端组件4.1 模板不是通用 prompt每一项都来自项目压测前面讲的都是结构和方法论这一章我直接放出三个我自己压测过很多轮的模板。这几个模板可以直接复制到自己的项目里改掉项目名和技术栈细节就能用。但我要先说明一件事你的模板必须来历清晰。我写这些模板不是从网上抄来的而是经过至少几十次对话验证、反复调整得到的——每一条规则背后都有一个具体的失败案例。你如果直接用可能需要根据自己的项目情况微调这很正常。4.2 场景一新接口开发的整条链路--- description: 按团队规范开发一个新的 API 接口包含路由、Service、校验、类型定义 argument-hint: 接口用途描述如创建工时记录 --- 请开发一个 {{argument}} 的 API。必须完成以下步骤 ## 步骤 1. 在 src/features 下定位所属 feature 目录确认路由设计遵循 RESTful 风格 2. 设计请求 / 响应 DTO类型必须写在 src/features/{模块}/api/types.ts 3. 编写 zod 校验 schema统一在路由入口处执行校验禁止在 service 里散落校验逻辑 4. 在 service 层实现核心业务逻辑要求 - 所有数据库操作使用事务如涉及多表 - 业务异常返回标准错误码不直接抛裸 Error 5. 在路由层做错误边界处理用 try/catch 包裹 service 调用并统一格式化响应 6. 修改完成后补充对应的集成测试测试文件放在同目录 __tests__ 下 ## 输出要求 - 列出所有创建/修改的文件路径 - 对每个文件给出核心代码和一两句说明 - 最后必须附上一份 curl 示例请求和预期响应示例这个命令模板背后是我最痛苦的经历早期让 AI “写一个接口”它会只给我一个路由函数把参数解析、业务逻辑、错误处理全混在一个函数里然后我拿去 code review 时被团队批得狗血淋头。这个模板等于把所有 review 意见前置了AI 生成的东西第一次就能过审。4.3 场景二生成符合设计稿的前端组件--- description: 根据描述或参考设计稿生成 React 组件 argument-hint: 组件需求描述功能、数据来源、交互、样式要求 --- 请生成一个 React 组件需求如下{{argument}} ## 强制要求 1. 组件放在 src/components 或对应 feature 目录props 设计遵循单一职责原则 2. 使用 TypeScript 严格模式props 必须有完整类型定义禁止使用 any 3. 样式方案优先 Tailwind class复杂交互状态用 CSS Modules 4. 数据请求组件内不直接调用 fetch通过 hooksReact Query封装 5. 必须考虑加载状态、空数据状态、错误状态的展示 6. 导出方式默认导出组件具名导出组件 props 类型 ## 完成后检查 - 组件是否可在 noSSR 或 CSR 场景正常工作 - 是否包含 a11y 基础支持role、aria-label、键盘操作 - 是否存在无意义的重新渲染useCallback / useMemo 使用是否合理我建议每个项目都保留几个这类“生成模板”。它的价值不光是让 AI 生成代码而是让 AI 生成的代码天然符合你团队已经达成共识的规范。比如你的团队已经约定“组件内不直接 fetch”如果不用模板你得每次对话都提醒它用了模板之后一次都不用。4.4 场景三把脏活累活安全地交给 AI还有一种场景AI 特别适合干但你不给模板又很容易翻车批量重构。--- description: 执行一个安全的批量重构操作 argument-hint: 具体重构目标和范围 --- 执行重构{{argument}} ## 安全规则 1. 先运行 pnpm typecheck 确认重构前代码状态记录基线错误数量 2. 重构过程保持小步提交每修改完一个文件或逻辑单元就运行类型检查和相关单测 3. 如果重构涉及公共函数签名、组件 props 变更必须先全项目搜索引用点逐个修改 4. 禁止使用全局查找替换必须人工确认每个替换点 5. 重构完成后运行 pnpm typecheck 和 pnpm test对比基线新增错误必须先修复 6. 如果过程中发现超出范围的代码异常停止并报告不擅自扩展范围为什么这个模板能兜住底因为 AI 在批量重构时最怕两件事一是改到一半忘了前面改了什么导致逻辑不自洽二是为了“完成用户请求”而不顾测试状态把所有文件一次性改完然后告诉你搞定了。加了“小步提交”和“基线对比”这两条之后AI 的行为模式会明显收敛——它会在改完每个逻辑单元后停下来检查而不是莽到最后一刻。5. 模板体系常见的坑我从失败里总结出的三条红线模板不是越多越好也不是写完了就能一劳永逸。以下三个坑是我实际踩过的每条对应一个反面教训。5.1 坑一CLAUDE.md 越写越长AI 反而越来越“笨”我早期犯过的错误是每遇到一个问题就往 CLAUDE.md 里加一条规则。半年以后这个文件超过三百行AI 确实每次都能看到它但它能记住的优先级是有限的。后来我意识到Claude Code 的上下文处理跟你和人交流是一样的——背景信息太长重要的约束就会淹没在琐碎细节里。我的解法是三层归档根目录 CLAUDE.md 只放“底线级规范”技术栈、安全红线、目录结构子目录 CLAUDE.md 放“模块级规范”那些“知道更好、不知道也不致命”的信息放到一个名为 AGENTS.md 或 docs/ai-context 的文件里通过根目录文件中的一行注释引用。这样 AI 在绝大多数任务里看的是精简版遇到对应模块任务时才去加载全量细节。5.2 坑二模板规则与实际代码脱节AI 给出过期方案这是我认为最危险的一个坑因为它不容易被察觉。CLAUDE.md 里的规范如果和实际代码库不一致——比如你把包管理器从 yarn 换成了 pnpm但模板里忘了改AI 就会在每次生成代码时一本正经地执行旧规范。最离谱的一次我遇到过 AI 按照模板里的旧接口签名去生成新代码结果整个模块编译都过不了花了大半天排查才发现模板里写的接口是三个月前的版本。所以我现在给团队定了一条纪律CLAUDE.md 和 commands 模板必须纳入代码审查范围。凡是修改依赖、切换框架、调整目录结构的 PR必须同步检查是否需要更新模板文件。这一步不做模板迟早变成一本过期的百科全书。5.3 坑三命令模板写得太满把 AI 限制成了翻译工具命令模板的职责是“定义步骤和标准”不是“替 AI 思考每一步”。有些同事写 command 模板时会把每一步都精确到离谱的程度比如“在终端执行命令 X然后把输出粘贴到文件 Y 中”——这种模板执行起来确实很听话但代价是你失去了 AI 的自主判断力。我的亲身体会是最合适的粒度是——告诉你 AI 要什么结果和需要遵守的边界过程中的方法决策由它自己发挥。比如在重构命令里我规定“小步提交”和“基线对比”但我不会规定它必须用什么拆分策略、先改哪个文件。这种方法既保证了结果可控又保留了 AI 在具体任务上的灵活性。6. 模板的演进从复制粘贴到内化成团队语言6.1 让模板仓库与代码仓库共同成长一个模板体系真正的成熟标志不是初始写得有多全而是它能不能跟随项目一起进化。我的做法是在团队内部维护一个templates/目录和代码仓库同分支管理。每次遇到新的 API 风格、新的技术选型或新的坑就把经验沉淀进对应模板并在 PR 描述里写上更新理由。三个月下来这批模板已经变成了团队在工程规范上的“活文档”——新人看模板比看入职文档上手快得多。这个目录的具体结构大概是这样的templates/ CLAUDE.md # 根级模板 commands/ review.md # 代码审查命令 commit.md # 提交信息生成 api.md # 新接口开发 component.md # 前端组件生成 refactor.md # 安全重构 docs/ ai-context.md # 长期背景知识每一条新增的规则都配一行注释说明它解决的问题。比如# 2025-03-12所有新接口必须返回统一错误码格式 # 背景某次线上事故是因为 service 层抛了裸 Error导致前端无法识别错误类型这样过几个月后回看模板你能清楚地知道每条规范是怎么来的、应不应该继续保留。6.2 从个人技巧升维成团队协作基础设施最后我想说Claude Code 的模板和人的“个人歌单”有类似之处自己用得很爽的模板不一定适合团队团队真正用的是那套经过统一校准、更新有纪律、职责边界清楚的东西。我们团队在把所有模板纳入代码审查后的变化非常直观新人有更低的试错成本老的工程师在 review AI 代码时不用反复纠正同一类错误跨模块协作时大家看到 AI 生成代码的风格也趋于统一。我的建议是不管你是个人开发者还是团队负责人都值得花一个下午把现有的 CLAUDE.md 和 commands 整理成这套结构。不用一次到位先把最痛的让 AI 重复做过的三件事固化成命令把项目里最容易踩的三条坑写进模板然后让模板跟着项目自然生长。试过之后你大概率会同意模板的维护成本远远低于它在未来无数次对话里帮你省下的返工成本。