Claude Code 模板体系实战：用 CLAUDE.md 和斜杠命令固化团队经验

1. 与其每次苦口婆心重新交代不如把模板体系先搭起来先说个我自己的真实场景。接手一个中等规模的项目代码量不算大但约定特别多——模块划分方式、命名规范、测试要求、数据库访问层的使用限制这些东西散落在代码里、文档里、甚至老同事的脑子里。我每次打开终端敲下claude都要花上几分钟把这些背景重新讲一遍。更烦的是讲到第三轮对话它可能就忘了开头说的约束又开始按它自己那套通用最佳实践来写代码。我大概忍了三周然后下定决心做一件事把所有反复交代的内容固化下来变成一套可以随时加载的模板。这就是 claude-code-templates 的由来。它不是简单地把提示词存成文本文件而是一套把项目经验、团队约定、个人偏好编码进 AI 协作流程的系统。这篇文章把我沉淀这套模板的完整思路和实操方法写出来包括模板有哪几种形态、目录怎么组织、内容怎么设计、真实项目里我留下了哪些模板、以及踩过哪些坑。适合两类人一是刚接触 Claude Code、只知道在终端里对话的新手想搞明白除了一次次提问之外还有哪些玩法二是已经用了一段时间、但觉得每次都要重复交代项目背景、想系统提升效率的人。先说一句总结性的话模板的价值不在少打几个字而在让 AI 的输出质量稳定下来。理解了这句话后面的所有内容就都顺了。2. 模板的三种形态记忆文件、斜杠命令与提示词片段我在实际使用中发现很多人把模板理解成单一的东西其实 Claude Code 里的模板至少可以分成三个层次各自的职责完全不同。用错层次效果会大打折扣。2.1 CLAUDE.md项目的长期记忆CLAUDE.md 是放在项目根目录下的一个 Markdown 文件作用是给每一轮对话提供项目背景和长期约束。它有点像你在入职第一天拿到的《团队新手指南》里面写清楚这个项目是干什么的、技术栈是什么、有哪些雷区、代码怎么组织。我建议每个项目的第一份 CLAUDE.md 至少包含这几块内容项目一句话概述让 AI 快速建立我在看什么项目的认知。技术栈与关键依赖框架版本、语言特性、用了哪些重要库。注意别把 package.json 整份贴进去挑真正影响编码决策的。目录结构说明不用列全所有文件重点标注几个核心目录的职责。编码约定比如错误处理统一用 Result 模式组件命名用 PascalCase禁止直接改数据库表结构。常用命令构建、测试、lint 分别是什么。已知的坑这块最有价值。比如某些老模块不要动重构计划排期未定这个 API 在 v2 版本已废弃。有个细节容易忽略CLAUDE.md 应该放在项目根目录这样只要在这个项目里启动 Claude Code它就会自动读取。如果你有跨项目的通用偏好比如所有回复用中文代码注释用英文可以在用户目录下放一份全局的 CLAUDE.md让所有项目共享。2.2 斜杠命令把高频操作变成一键调用斜杠命令是第二种形态也是最像模板的东西。在.claude/commands/目录下放一个 Markdown 文件比如review.md就可以在对话里用/review直接触发。命令文件可以用 YAML 格式的 frontmatter 写描述信息正文写指令内容。我的经验是斜杠命令适合两种场景一是操作类的固定流程比如审查改动写测试生成提交信息二是角色类的临时切换比如你现在是数据库专家专门分析慢查询。这两种场景的共同点是输入输出比较确定可以被标准化。和 CLAUDE.md 的区别在于CLAUDE.md 是每轮对话都在后台加载的背景知识斜杠命令是用户主动触发的执行流程。所以不要把项目背景全塞进命令文件里——你只需要在命令里写先读一下 CLAUDE.md剩下的让 AI 自己取。2.3 提示词片段临场拼装的最小单元第三种形态最轻量就是一段可以复用的提示词片段。比如一个好的需求描述模板、一个 Bug 报告模板、一个重构说明模板。你可以把它们存在单独的 Markdown 文件里需要的时候直接复制粘贴配合斜杠命令的$ARGUMENTS参数一起用。我自己的习惯是建一个prompts/目录里面按场景分类存片段比如需求描述.md、Bug报告.md。写需求的时候先套用这个骨架把信息填满再丢给 AI。这样做的价值是逼自己把话说完整——很多人之所以对 AI 的输出不满意是因为输入本身就不完整模板帮你兜住了这部分。三种形态的关系可以这样理解CLAUDE.md 是这个人长期记住的东西斜杠命令是这个人按固定流程干活的方式提示词片段是你递给他的标准化任务单。三者配合使用才能覆盖从背景知识到具体执行的全部环节。3. 从零搭建一套模板库目录结构与实操顺序理论讲完直接上操作。我自己现在用的目录骨架是这样的project-root/ ├── CLAUDE.md ├── .claude/ │ ├── commands/ │ │ ├── review.md # /review 代码审查 │ │ ├── bugfix.md # /bugfix Bug 定位与修复 │ │ ├── refactor.md # /refactor 重构 │ │ ├── docs.md # /docs 生成文档 │ │ └── feature.md # /feature 新功能开发 │ └── settings.json # 按需配置 └── prompts/ ├── 需求描述.md ├── Bug报告.md └── 提交信息.md3.1 目录结构的设计思路.claude/commands/里的文件名决定了斜杠命令名review.md对应/reviewbugfix.md对应/bugfix。推荐用动词命名一眼就能看出这个命令干什么。prompts/目录放在项目外层还是内层取决于你的使用习惯。我的建议是项目通用的提示词骨架放在全局目录项目特有的放项目内。比如需求描述模板这种几乎所有项目都通用的放全局这个项目特有的数据迁移检查清单这种放项目内。还有一个很容易被忽视的点模板目录本身也是代码需要版本管理。我习惯把这些文件纳入 Git 仓库团队成员一起维护。谁发现自己常犯的错误被 AI 漏掉了就在 CLAUDE.md 里加一条谁发现审查模板不够严格就改命令文件。模板库会随着使用越来越贴合实际。3.2 第一份 CLAUDE.md从最小可用开始很多人一上来就想写一份巨无霸 CLAUDE.md把项目所有细节都塞进去。我的建议是反着来先写最小可用版本只包含 AI 不问就会出错的信息。以下几类信息如果不写AI 大概率会猜错所以必须优先写入技术栈和版本约束。比如后端是 Python 3.12 FastAPI前端是 React 18 TypeScript。测试命令和测试约定。AI 改完代码想验证得知道跑什么命令。代码风格里最容易冲突的部分。比如缩进用 4 空格字符串统一单引号。项目特有的领域规则。比如金额单位统一为分禁止使用浮点运算。我自己的第一版 CLAUDE.md 长这样# 项目背景 XX 电商平台的后台管理系统主要面向运营人员。 # 技术栈 - 后端Python 3.12 FastAPI SQLAlchemy 2.x - 前端React 18 TypeScript Vite - 数据库PostgreSQL 15 # 常用命令 - 启动后端uvicorn app.main:app --reload - 跑测试pytest - 前端构建npm run build # 编码约定 - 后端禁止在业务逻辑里直接操作 session必须走仓储层 - 金额单位统一为分int禁止 float - 新增接口必须写 OpenAPI 文档注释 # 已知的坑 - legacy/payment 模块是历史遗留代码重构前先找负责人确认 - 生产环境数据库连接串从环境变量读取不要在代码里硬编码这份 CLAUDE.md 一共十几行但覆盖了 AI 最容易犯错的信息。之后每次遇到AI 反复犯同一个错误的情况就追加一条约定慢慢它就变成了一份详细的项目手册。3.3 第一个斜杠命令代码审查模板斜杠命令的写法非常简单我拿代码审查命令做示例。在.claude/commands/review.md里写上--- description: 审查当前工作区的代码改动 --- 你是一名资深代码审查者。请先阅读 CLAUDE.md然后审查当前工作区的改动。 审查重点 1. 是否符合项目编码约定 2. 是否存在边界条件遗漏空值、并发、超时 3. 是否有明显性能问题如 N1 查询、循环里做 I/O 4. 是否有安全风险如 SQL 注入、越权 输出要求 - 按严重程度分三类给出问题列表严重 / 建议 / 可选 - 每个问题写明文件路径、行号和修改建议 - 如果没发现问题明确说未发现明显问题文件名review.md决定了命令名/review启动 Claude Code 后直接输入/review就会执行。frontmatter 里的description会在输入/时显示出来方便你记住每个命令是干什么的。这里有个我自己用得很顺的技巧命令里可以加$ARGUMENTS占位符让命令接收额外参数。比如把上面的命令升级成审查指定文件--- description: 审查指定文件的改动 --- 请审查以下文件的改动$ARGUMENTS然后在对话里输入/review app/services/order.py$ARGUMENTS就会被替换成app/services/order.py。这个机制让我可以把一套流程复用到不同目标上。4. 模板内容设计给 AI 划重点的正确方式模板文件建好之后真正决定效果的是内容质量。我用了大半年总结出三个核心设计原则。4.1 先告诉 AI你是谁再告诉它干什么很多人写的指令命令一上来就是请帮我审查代码请生成测试AI 确实会执行但执行质量取决于它临场判断的角色。如果模板里先设定角色结果会稳定很多。比如审查命令里写你是一名资深代码审查者和请审查代码效果差别很大。前者会让 AI 主动对照行业标准去挑问题后者可能只是简单过一遍。同样的道理适用于所有角色类模板性能优化时设定你是专注于数据库性能的 DBA代码重构时设定你有大型项目重构经验优先保证行为不变。角色设定不是玄学它本质上是激活 AI 在训练中学到的特定领域知识。给的角色越具体匹配到的知识就越精准。4.2 用限定范围代替全面覆盖新手写模板的典型毛病是贪多求全。比如写审查模板把性能、安全、规范、可读性、测试、文档全列进去结果 AI 每项都浅尝辄止。我的做法是反过来的一次模板只盯一个核心目标。以代码审查为例我拆成三个独立命令/review整体审查范围广但深度适中。/review-security专注安全审查逐行排查注入、越权、敏感信息泄露。/review-perf专注性能审查重点看数据库查询、循环、缓存策略。这样做的好处是每次调用时 AI 的注意力高度聚焦。输出质量明显比一次审所有要高。原则很简单AI 的工作记忆是有限的你把它的注意力分散到十个方向每个方向就只能分到十分之一的深度。4.3 输出格式一定要钉死模板里最容易偷懒的地方是输出格式。很多人写请给出审查结果就完了AI 每次返回的结构都不一样你还得二次加工。我的习惯是在模板里明确输出格式甚至给出示例骨架。比如审查模板里规定输出格式 ### 严重问题 - [文件路径:行号] 问题描述修改建议 ### 建议改进 - [文件路径:行号] 问题描述修改建议 ### 可选优化 - 列表形式逐条列出规定输出格式有三个好处一是结果稳定可预期可以直接做后续处理二是迫使 AI 在结构内思考不容易漏掉某类问题三是方便对比不同模板的效果。这个习惯我强烈建议养成哪怕多写两行字也是值得的。4.4 上下文注入要控制密度模板里的信息不是越多越好。之前我犯过一个错把项目全部文档都塞进 CLAUDE.mdAI 每轮对话光读背景就消耗了大量上下文窗口聊到一半开始失忆前面说好的约定后面就忘了。上下文窗口是稀缺资源模板设计的本质是在这个有限空间里做信息取舍。我的经验是 CLAUDE.md 控制在 200 行以内只保留不写就会出错的信息。那些写了也行但不写也能猜对的信息一律不写。如果确实需要更详细的背景可以在命令里引用具体文件路径让 AI 按需读取而不是把全文放进模板。5. 我在真实项目里沉淀下来的五套模板这部分直接上我在项目中实际在用的模板你可以直接复制改一改。每个模板我都简单说一下设计的理由方便你理解哪些地方可以按自己项目调整。5.1 代码审查模板review.md前面已经展示过了补充一个实战要点。经过多次迭代我在最终的 review.md 里加了一条特殊约束特别提醒 - 不要只停留在代码表面重点检查调用关系和数据流 - 如果发现问题先确认 CLAUDE.md 里是否有相关约定 - 不确定的问题标注存疑不要臆断加存疑标注是因为我发现 AI 会把不确定的问题当成确定问题报出来误导开发者。标注机制让它有机会表达不确定性反而更可信。5.2 Bug 定位模板bugfix.md这是我最常用的一个模板解决的是AI 凭感觉猜 Bug 原因的问题。核心思路是强制 AI 先收集证据再下结论--- description: 定位并修复指定 Bug --- 请按照如下流程定位 Bug$ARGUMENTS 1. 先阅读 CLAUDE.md了解项目背景和约束 2. 找出与问题相关的代码入口和调用链 3. 列出可能导致该问题的所有可能原因按概率排序 4. 对每个可能原因说明如何验证 5. 确认根因后给出修复方案注意不要引入新的问题 输出要求 - 先输出问题定位过程相关文件、调用链、关键日志 - 再输出根因分析明确判断依据 - 最后输出修复方案代码级建议这个模板的价值在于把 AI 引入先假设后验证的工程化思路。如果没有这个流程约束AI 经常跳过步骤直接给一个看起来合理的修复结果改完反而更糟。用了这套模板之后AI 的 Bug 修复成功率高了不止一个档次。5.3 重构模板refactor.md重构场景的特殊性在于风险控制。我见过太多 AI 重构后行为发生变化测试挂了或者 API 调用偷偷变了。所以我的重构模板里把保持行为不变放在最前面--- description: 对指定模块进行重构 --- 请对以下模块进行重构$ARGUMENTS 硬性要求 1. 行为完全不变输出结果与重构前一致 2. 不改变公共 API 签名 3. 不改变依赖关系 步骤 1. 先阅读 CLAUDE.md 和模块现有代码列出所有外部依赖和调用方 2. 给出重构计划目标结构、中间步骤、风险点 3. 逐步执行重构每步完成后自检行为一致性 4. 最后给出变更清单标注影响面 输出要求 - 重构计划优先确认不要直接改代码 - 变更清单里注明每个文件的改动类型新增/修改/删除先确认计划再动手是我加的一个保险机制。AI 一旦进入执行模式很容易忽略全局影响。让它在动手之前先输出重构计划相当于给了你一个检查点可以在它还只改了一小部分的时候踩刹车。5.4 文档生成模板docs.md写文档这件事 AI 做得还不错但容易写成废话大全。我的模板核心是约束信息密度和结构--- description: 为指定模块生成文档 --- 请为以下模块生成技术文档$ARGUMENTS 要求 1. 先阅读 CLAUDE.md 和相关源码 2. 只记录不看代码就不知道的信息设计动机、关键逻辑、外部依赖、潜在陷阱 3. 不要复述代码本身不要堆砌 API 列表 文档结构 - 模块职责3 句话以内说明 - 关键设计列出 3 个以内的核心设计决策并说明为什么 - 使用方式带最小可运行示例 - 已知限制目前不支持的场景或已知问题这个模板的灵感来自我整理文档时的痛点——AI 生成的文档什么都写了什么都没用。限制它只写不看代码就不知道的东西文档价值立刻上来了。5.5 新功能开发模板feature.md最后一个模板是功能开发的起点。把需求描述、技术选型和实现计划强制拆开避免 AI 跳过需求讨论直接进入编码--- description: 按标准流程开发一个新功能 --- 请开发以下功能$ARGUMENTS 流程要求 1. 先阅读 CLAUDE.md明确技术栈和约束 2. 从需求中提炼出功能边界和验收标准 3. 如涉及数据库改动先给出表结构或迁移方案 4. 给出技术方案后再开始写代码 5. 写完代码后指出如何手动验证 输出要求 - 第一步只输出需求理解和验收标准等待确认后再继续 - 确认后输出技术方案包含关键文件改动清单这个模板是我对抗AI 太快动手的武器。它强制 AI 分阶段输出每一阶段都有确认节点。虽然交互步骤变多了但避免了返工。实测下来一次通过的几率大幅度提升整体时间反而是省了。6. 模板失效的常见原因与我的排查思路模板体系用久了必然会遇到突然不灵了的情况。我把最常踩的坑整理出来以及对应的排查方法。6.1 上下文溢出导致失忆表现前一阶段 AI 还能遵守模板约束后面慢慢开始偏离甚至忘了项目背景里的关键约定。原因大概率是上下文窗口被填满了。尤其在长对话或处理大文件时模板要求的背景信息和中间输出挤掉了后续的注意力空间。排查方法缩短单次任务的规模。比如审查代码时指定只审查某一个目录而不是整个工作区重构时分模块进行而不是一次改整个项目。如果任务确实很大就拆成多个对话而不是在一个对话里连续执行。6.2 模板写得太多AI 反而不知道听谁的表现模板里约束了 A 又约束了 B两者矛盾时 AI 表现得无所适从或者顾此失彼。典型例子是我曾经在重构模板里同时要求保持公共 API 签名不变和优化接口设计这两个诉求在有些场景下是冲突的。AI 无法判断优先级输出就两边讨好结果都不到位。排查方法遇到这种情况回到模板里明确优先级。比如在重构模板里加上如果保持签名与优化设计冲突以前者为准并在变更清单里标注冲突点供人工决策。模板里需要的是明确的优先级规则而不是一堆平行约束。6.3 模板与实际项目脱节表现模板引用的文件路径已经变了CLAUDE.md 里写的技术栈已经升级了命令执行时 AI 花大把时间纠错。这个坑最隐蔽。模板是静态的项目是动态的。我吃过一次亏CLAUDE.md 里写着数据库访问走仓储层但某次重构后这个约定已经废弃了AI 照着旧约定给我生成了一堆要废弃的代码。排查方法把模板维护当作项目日常工作的一部分。每当我意识到AI 执行结果和团队实际做法不一致时第一件事就是去检查模板哪里没有跟上。另外建议每隔一两个迭代抽十分钟过一遍 CLAUDE.md删除失效信息、更新路径和命令。这个行为看上去很琐碎收益却极大。6.4 版本更新导致语法或行为变化表现某天更新客户端之后原来的斜杠命令报错或者$ARGUMENTS不再生效或者 CLAUDE.md 的某些指令被忽略。Claude Code 迭代速度快模板语法和行为可能的兼容性调整。我遇到过一次 frontmatter 字段不被识别的情况排查了半天才发现是版本更新后的兼容问题。排查方法养成两个习惯。一是在模板文件里记录适用的版本范围二是更新客户端后先跑一遍最常用的几个命令做回归验证不用等真正用的时候才发现坏了。另外官方文档或更新日志里如果有行为变更说明值得花几分钟扫一遍。这套模板体系我在多个项目里用下来最深的体感是它把 AI 从一个每次都要重新认识的临时工变成了一个带着项目记忆的老同事。当然没有一套模板是放之四海皆准的你真正需要的可能只是其中两三个模板的雏形然后用日常使用中的反馈慢慢打磨让它们长成本项目的形状。最后再分享一个小经验刚开始不用追求完整先写一个 CLAUDE.md 和一个最常用命令的模板跑起来再说。模板这东西用起来才会发现缺什么闭门造车只会造出一堆没人碰的文件。