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 typecheck（TS 严格模式，禁止使用 any） - 测试命令：pnpm test（Vitest + React Testing Library） - Lint/Format：ESLint 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，通过 hooks（React 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 重复做过的三件事固化成命令，把项目里最容易踩的三条坑写进模板，然后让模板跟着项目自然生长。试过之后你大概率会同意：模板的维护成本，远远低于它在未来无数次对话里帮你省下的返工成本。
