1. 先搞明白Claude Code 里的模板到底指什么在 Claude Code 这个生态里模板是个被用得很泛滥的词。有人说模板是 CLAUDE.md有人说模板是 slash command还有人把整套项目脚手架也叫模板。这些说法都有道理但指向的东西完全不同。如果一开始不把这几个概念拆开后面搭模板库的时候一定会乱。我自己的理解是Claude Code 的模板体系分四个层次从下往上分别是 —— 项目记忆模板CLAUDE.md 及导入文件、交互命令模板自定义 slash command、技能模板Agent Skills、自动化钩子模板hooks。每一层解决的是不同问题但它们的共同点是把人和 AI 协作时反复使用的那套约定固化成文件放进仓库里随项目走。这四个层次里CLAUDE.md 是根基也是刚上手时最值得先搞的东西。它本质上是一份 Markdown 文档放在项目根目录下Claude Code 每次启动时会自动把它读进上下文。也就是说它不需要你每次手动声明而是像岗位说明书一样天然存在于会话的起点。很多刚接触的人会疑惑CLAUDE.md 和 README 有什么区别答案是定位完全不同。README 是给人看的项目介绍CLAUDE.md 是给 AI 看的协作协议。里面写的是代码风格偏好、构建命令、测试方式、禁止事项、项目架构约定。你不需要写得文采飞扬只需要写得像一份技术交接备忘录。所以第一篇内容我想先带你厘清这些概念因为后续所有模板搭建都是基于这四个层次展开的。理解错了层次后面的存储位置、加载机制、优先级规则全会搞混。1.1 四个模板层次各自的职责边界我用一张表先把四个层次的关系摆清楚后面每个细节都会展开讲层次载体形式加载方式核心职责项目记忆CLAUDE.md 及 imports 文件自动加载定义项目基线、规范、架构命令模板.claude/commands/*.md斜杠触发固化高频交互流程技能模板.claude/skills/*/SKILL.md按需调用沉淀可复用的专项目能力自动化钩子.claude/hooks/*.js事件触发在关键节点强制插入行为先说项目记忆这一层。它管的不是某个具体任务怎么做而是这个项目长期不变的事实。比如这个项目是 monorepo 还是单仓、前端用 Vue 还是 React、测试跑什么命令、代码提交前必须过 lint。这些内容一旦写进 CLAUDE.mdAI 每次干活都会默认遵守你不用反复叮嘱。命令模板更像快捷指令。你想让 AI 执行一次代码审查、生成一份周报、做一个数据库迁移方案直接/review、/weekly-report、/migration-plan敲下去就行。每个命令背后是一个 Markdown 文件文件里写清楚这个指令的执行步骤、输出格式、质量标准。技能模板是 Claude Code 后续版本逐步完善起来的东西比命令模板更重。它不是一段 prompt而是一套带文件结构的技能包包含 SKILL.md 主文件、示例代码、参考文档。适合沉淀那些需要背景知识才能完成的能力比如如何按团队规范写 Rust 代码如何分析前端性能瓶颈。hooks 是纯自动化层。它不依赖对话而是绑定某个事件比如文件保存、命令执行前、对话开始触发时执行一段脚本把结果注入会话。我拿它做过挺多事后面专门讲。1.2 CLAUDE.md 是项目的根模板优先级最高四个层次里最常被问的问题就是优先级。Claude Code 加载配置时遵循的原则是项目优先于用户全局用户全局优先于内置默认。具体到 CLAUDE.md加载顺序大概是这样的内置的默认行为除非你自定义否则 AI 会有一套通用逻辑用户级 CLAUDE.md放在~/.claude/CLAUDE.md作用于本机所有项目项目级 CLAUDE.md放在项目根目录作用于当前项目。同级之间有冲突时层级越靠近项目的配置越有说服力。这意味着如果你在项目级 CLAUDE.md 里写禁止使用 TypeScript 的 any 类型但用户级 CLAUDE.md 里说类型可以宽松处理那么 AI 会遵守项目级的规定。这背后的逻辑也很直接项目级配置是特定仓库的硬约束用户级配置是个人偏好。硬约束优先于偏好否则团队协作就没法开展。另外要留意一个细节CLAUDE.md 支持路径语法导入外部文件。比如你有一个超长的代码规范文档不想全部塞进 CLAUDE.md 里可以在 CLAUDE.md 写一行docs/coding-standards.mdAI 会主动读取这个文件的内容。这相当于给 CLAUDE.md 做了外挂模块非常适合拆分大文档。我自己一般会在项目根目录建一个claude/目录里面放规范拆分文件根 CLAUDE.md 只保留最核心的约定。这样整个模板体系的入口很薄但展开后内容非常丰富。很多人一上来就把几十条规范堆进 CLAUDE.md结果上下文被大量基线信息占掉反而影响 AI 处理实际任务的效率。2. 模板仓库怎么搭目录结构、命名规范与同步策略理清了四个层次接下来要解决的是放哪里怎么命名多项目怎么同步。2.1 .claude 目录下的分工命令和技能怎么组织Claude Code 的配置目录分两种项目级.claude/和用户级~/.claude/。项目级的配置跟着仓库走提交到 Git 后团队所有人都能共享用户级配置只属于你个人适合放与特定仓库无关的通用命令。默认情况下项目的.claude/目录结构长这样.claude/ ├── CLAUDE.md # 项目根配置也有不少项目直接放根目录 ├── commands/ # 自定义 slash 命令 │ ├── review.md │ ├── weekly-report.md │ └── migration-plan.md ├── skills/ # Agent Skills 技能包 │ ├── rust-audit/ │ │ ├── SKILL.md │ │ └── examples/ │ └── perflog/ │ ├── SKILL.md │ └── references/ └── hooks/ # 自动化钩子 ├── pre-commit.js └── session-start.js如果你使用/init生成初始配置Claude Code 会自动帮你把基本骨架搭好。但实际干活时你会发现默认骨架远远不够命令和技能需要按你的工作流重新设计。命令文件是 Markdown 格式文件名就是触发命令的名称。比如你创建一个commands/review.md在对话里输入/review就会触发这个文件的内容。文件头部有 YAML 元信息用来声明参数、描述、模型配置等主体部分写执行指令。这里有个值得注意的点命令文件里可以使用参数占位符。比如$ARGUMENTS代表用户输入的所有参数$1、$2代表按空格切分的第一个、第二个参数。这个能力很实用。我写过一个/checklist命令用户可以直接输入待办事项1 待办事项2命令模板会自动转化为格式化的任务清单。2.2 命名规范与语义化设计让模板一看就懂模板库最怕的不是没人用而是命名混乱导致没人敢用。我给模板命名定了几条硬规矩动词开头review、refactor、migrate、optimize、generate。命令的本质是让 AI 做动作动词开头最直观。不用缩写除了极少数公认缩写比如db一律写全拼。checkout不要写成comigration不要写成mig。缩写省不了多少打字时间但会带来大量理解成本。按场景分目录命令多了之后单一目录会非常拥挤。.claude/commands/下可以建子目录比如commands/code-review/、commands/ops/然后通过/code-review/xxx的方式触发。这也是官方支持的能力。文件内写明适用场景每个命令文件开头用一行说明什么时候用这个命令而不是只写这个命令做什么。后者是功能的描述前者才是使用决策的关键。技能目录的命名我倾向于名词短语用途的组合比如rust-audit、react-state-check。技能包本质上是带知识库的助手命名要表达出知识域的边界而不是动作。还有同步策略。如果你在多个项目里都要用同一套命令把它们放进~/.claude/commands/是最直接的办法。用户级命令对所有项目生效不需要每个仓库都复制一份。但要注意用户级命令读不到项目上下文命令内容里涉及路径、依赖、代码结构的部分得用让 AI 自己探索的方式写而不是硬编码某个项目的具体路径。如果是团队协作项目级.claude/进 Git 是标配。团队里每个人 clone 仓库后用/init或直接重启会话就能获得同一套模板。这里我要提一个细节CLAUDE.md和.claude/commands/里的命令文件建议让 AI 在生成时感知变更。你在代码评审里可以加一条任何涉及 AI 协作规范的改动都需要同步更新对应的命令模板和 CLAUDE.md。否则模板库很快就会和实际工程脱节。3. 从零手写一套可复用模板代码审查、技术方案、发布清单这一章我会贴出三个我实际在用、且验证过效果的模板供你直接抄走改改就能用。3.1 代码审查模板把随意看看变成结构化检查很多人在 Claude Code 里做代码审查就是丢一段代码进去说帮我 review 一下。这种用法的问题很明显AI 不知道你的审查标准是什么不知道你关心的重点是什么最后给出的反馈往往大而全但缺乏针对性。我自己写的/review命令模板如下--- description: 对指定文件或整个 PR 进行结构化代码审查 argument-hint: [文件路径] 或 [PR 描述] --- 你是一位资深代码审查者。请基于以下步骤审查代码 1. 读取目标文件或 PR 变更内容 2. 从以下五个维度给出审查意见每个维度必须有具体行号和示例 - 正确性是否存在逻辑错误、边界条件遗漏、并发问题 - 安全性是否存在注入、越权、敏感信息泄露风险 - 可维护性命名是否清晰结构是否合理是否有重复代码 - 性能是否存在明显不必要的计算、重复查询、内存占用问题 - 测试关键路径是否有对应测试测试是否覆盖边界条件 3. 输出格式 - 先给总体结论通过 / 需修改 / 需重新设计 - 再用表格列出问题清单包含严重级别、文件行号、问题描述、修改建议 - 最后给出优先级最高的 3 个改进建议 注意如果改动涉及数据库迁移、API 兼容性、第三方依赖变更必须额外检查这三项。这个模板的价值在于它把审查维度固定下来AI 不会因为今天心情不同给出风格完全不同的审查结果。团队里的每个人用同一套模板审查质量的标准也趋近一致。实际使用下来我会搭配一个技巧审查前先让 AI 运行测试和 lint把结果一起纳入审查上下文。比如在对话里先跑npm test再执行/review src/xxx.tsAI 能结合运行时反馈做更有依据的判断。但注意命令模板本身不要写成自动运行测试——那属于 hooks 的职责命令里越俎代庖反而容易出问题。3.2 技术方案模板让 AI 先写方案再写代码我见过太多人让 AI 直接写代码写完发现设计完全不对。真正高效的用法是先让 AI 产出技术方案人审完方案再让它写实现。这个思路落到模板里就是一个/design命令--- description: 根据需求生成技术方案设计文档 argument-hint: 需求描述 --- 你是一位资深架构师。请根据以下需求生成技术方案 需求$ARGUMENTS 方案需要包含以下部分 1. 背景与目标明确要解决的问题和非目标 2. 技术选型列出候选方案对比优缺点并给出选择理由 3. 模块设计包括核心数据结构、接口定义、模块划分 4. 数据库设计如涉及表结构、索引、数据流转 5. 风险与对策列出可能出现的问题和预防措施 6. 分阶段实施计划按里程碑拆分每阶段有可交付物 输出要求 - 方案以 Markdown 格式输出包含必要的代码示例 - 如果需求中有不清楚的地方先列出假设条件再基于假设输出方案 - 方案末尾必须有待确认问题列表方便人工评审时逐条讨论。这个模板用起来最妙的地方是最后一条待确认问题列表。AI 写方案时一定会遇到需求模糊的地带与其让它猜不如让它把假设摆出来。你评审方案时只需要对着问题列表逐条确认比对着整篇方案找漏洞轻松得多。我自己通常会在确认完方案后追加一句根据确认后的方案写出第一阶段的代码。这样 AI 既能保持设计一致性又不会一上来就陷入细节。3.3 发布检查清单模板把流程性事务压进一条命令发布这种流程性事务最大的痛点是总会漏一步。哪怕你列了检查清单人总有忙中出错的时候。让 AI 在发布前帮你逐项核对是最能发挥模板工具组合价值的场景。我写的/release-check模板--- description: 发布前的全流程检查清单 argument-hint: 可选填发布版本号和环境 --- 你是一位发布负责人。请对当前项目执行发布前检查 版本$1如为空则读取 package.json 中的版本号 环境$2如为空则默认生产环境 请逐一检查以下项目每项都给出通过 / 不通过的结论 1. 版本号与变更日志是否匹配 2. 所有测试是否通过执行 npm test 或项目配置的测试命令 3. lint 与类型检查是否通过 4. 构建产物是否成功生成 5. 是否存在未提交的代码变更git status 检查 6. 数据库迁移脚本是否有配套回滚方案 7. 环境变量配置是否与部署环境匹配 8. 依赖锁定文件package-lock.json / pnpm-lock.yaml是否更新 9. 文档是否同步更新README、API 文档等 10. 是否有已知的遗留问题检索 TODO、FIXME 最后输出 - 检查结果总览表 - 未通过项目的具体原因和修复建议 - 如果全部通过给出可以发布的结论否则给出阻断原因这个模板的运行机制是命令模板 工具调用AI 在检查过程中会自己读取文件、执行命令然后汇总结果。通过后你也可以接着让它执行回滚预案演练——用/rollback-plan命令生成一份与本次发布配套的回滚方案这才是完整的发布闭环。4. 模板与上下文管理优先级冲突与瘦身策略搭模板库很容易遇到一个问题随着时间推移CLAUDE.md 越来越长技能包越来越多AI 的上下文被大量背景知识占据真正处理任务的空间反而变小了。上下文的管理能力直接决定了模板体系的上限。4.1 模板冲突时的裁决机制谁说了算模板一多冲突不可避免。比如用户级 CLAUDE.md 里写了所有输出用中文项目级 CLAUDE.md 里写了代码注释使用英文。这时候 AI 听谁的按照上一章说的规则项目级优先于用户级。但实战中还有更隐蔽的冲突——命令模板和 CLAUDE.md 的冲突。举一个实际例子CLAUDE.md 里定义了本项目禁止直接修改数据库结构必须先出迁移文档但你写的某个命令模板里为了图省事直接让 AI 输出 ALTER TABLE 语句。这时候两套指令打架AI 的行为会不稳定。我的处理原则是CLAUDE.md 定义的是不可违背的约束命令模板定义的是可执行的流程。命令模板在执行前必须先读取 CLAUDE.md如果有冲突以 CLAUDE.md 为准。具体到实现层面我会在命令模板的开头加一行提示例如开始执行前先阅读项目根目录的 CLAUDE.md确保本命令的操作与其中的约束不冲突。这行提示看着简单但实际能避免大量AI 按命令干活却违反项目规范的问题。原因在于 Claude Code 本身具备较好的指令层次理解能力明确声明优先级后它能更自觉地遵守约束。另外hooks 层也可能和命令层冲突。比如你写了一个 pre-commit hook 强制检查代码格式但某个命令模板让 AI 跳过检查直接提交。这种冲突在实现时要统一处理hook 是机器层面的硬门禁命令是对话层面的软流程硬门禁永远不能绕过。4.2 上下文窗口的取舍模板不是越多越好Claude Code 的上下文窗口再宽也是有限资源。每次会话都会加载 CLAUDE.md、技能描述、命令定义这些内容本身不产生输出但会占用上下文窗口。我在实际项目里踩过一个大坑CLAUDE.md 写了 300 多行包含所有历史决策、完整架构文档、全部代码规范。结果每次开新会话AI 要花费很多注意力消化这些内容处理简单问题时反应反而变慢。这就像你给新同事发了一本几百页的手册他翻完手册才能开始干活。后来我采用的瘦身策略是CLAUDE.md 只保留最高频、最硬性的约束长文档通过imports按需加载。具体做法CLAUDE.md 控制在 60-80 行以内只写项目一句话描述和技术栈构建、测试、lint 命令不可违背的硬约束比如禁止直接操作生产数据库关键目录结构说明长文档拆到claude/目录下通过claude/coding-standards.md这种方式按需导入。如果你判断某个任务不需要完整标准可以在对话里明确告诉 AI不用读取 coding-standards.md。命令模板保持流程指挥属性不塞大段知识内容。如果某个命令需要大量专业知识把它改造成技能包Skill通过技能目录单独管理。这套策略的核心思想是**上下文是预付成本模板是资产不要让所有资产同时占用成本。**把模板分层、按需加载才能让上下文始终服务于当前任务。4.3 技能包的正确打开方式按需注入而不是常驻Skill 机制之所以比把知识写进 CLAUDE.md 更优雅是因为它天然支持按需加载。技能包有自己独立的 Markdown 主文件和资源目录AI 在判断任务需要时会主动读取技能包内容读取后才具备对应的专业能力。举个我自己的例子。我参与过一个 Rust 项目团队要求所有 unsafe 代码必须有安全注释和审查记录。这项要求如果写进项目 CLAUDE.md会占用大量篇幅如果不写AI 又容易忽略。我的处理是把rust unsafe 代码审查规范做成一个技能包.claude/skills/rust-unsafe-audit/里面包含 SKILL.md审查步骤、示例文件合规示例、违规示例、参考资料官方文档摘录。然后在一个/audit命令模板里这样写--- description: 对 Rust 代码中的 unsafe 块进行安全审查 --- 请先加载 rust-unsafe-audit 技能包然后扫描当前代码中所有 unsafe 块 按技能包中的审查规范逐一检查输出问题清单和整改建议。这样做的效果很明显普通代码审查任务不会把 unsafe 审计的规范加载进来只有明确需要审查 unsafe 时AI 才去读取技能包。上下文省下来了专业性也没有打折扣。技能包的设计还有一个细节SKILL.md 里要写清楚这个技能的触发条件、不适用场景、输出格式。很多技能包失败的原因不是内容不够好而是 AI 不知道什么时候该用它。你写得越明确AI 的按需判断越精准。5. 实测中的几个坑与我的固定解法模板体系用了大半年踩了不少坑。这一章我把最有代表性的几个问题写出来每一个都附上我现在的固定解法。5.1 坑一命令模板和 CLAUDE.md 内容重复导致 AI 行为不稳定最早我写命令模板时习惯把相关规范也写进去。比如/review命令里写了代码必须有单元测试CLAUDE.md 里也写了新功能必须配套单元测试。看起来没问题但实际运行中 AI 有时会重复检查有时会只执行命令模板而忽略 CLAUDE.md行为非常不稳定。现在的固定解法是**CLAUDE.md 里的内容是状态命令模板里的内容是流程。状态类约束不要出现在命令模板中命令模板只描述流程和输出格式。**如果命令确实需要引用某个规范用一句参照 CLAUDE.md 中关于测试的要求来指引用而不是复制粘贴。5.2 坑二命令模板中的绝对路径换个环境就失效早期我的命令模板习惯写cd /Users/xxx/projects/my-app这类绝对路径。结果换台电脑、换个项目命令就废了。Claude Code 本身的工作目录就是项目根目录不需要也不应该在命令里指定绝对路径。如果命令需要操作特定文件用相对路径或者让 AI 先通过 glob 匹配找到文件再操作。比如先用 find 或 grep 定位 src/main.ts 文件再执行审查。这种写法在任何项目、任何环境下都能工作。5.3 坑三模板更新后AI 仍使用旧规则模板文件改了新会话里的 AI 应该读取的是新内容。但在某些长会话中AI 可能记忆了旧规则尤其是你已经对话很久、上下文很长的情况下更明显。我的固定解法是**重要模板更新后开新会话再执行关键任务。**如果必须在当前会话中使用可以先输入一句/clear清理上下文或手动让 AI重新读取 .claude/commands/review.md 文件。这招虽然朴素但非常有效能避免大量因为规则过期产生的返工。5.4 坑四hooks 误伤正常流程把模板变成陷阱hooks 是自动化程度最高的模板层也最容易闯祸。我写过两个失败案例一个是 pre-commit 检查强制要求所有提交信息包含 JIRA 单号结果本地临时提交经常被拦截另一个是 session-start 钩子自动执行git pull结果哪天本地有未提交改动直接冲突。现在我的 hooks 使用原则是hook 只做阻止危险行为和补充必要信息两件事不做任何有副作用的操作。比如 pre-commit 只检查不修改session-start 只注入环境信息不主动拉取。你如果想拉代码更新应该通过命令模板显式触发而不是让 hook 悄悄做。基于这个原则我把失败的 pre-commit hook 重写成了检测提交信息格式如果不匹配则提醒但不阻断把决定权还给人把 session-start hook 改成读取当前分支和最近一次提交信息输出到对话里作为基础上下文。后面这个改法在团队里反响很好每个人开新会话时都知道自己现在在哪条分支、改到哪一步了。5.5 格式与细节YAML 头部信息别马虎命令模板的 YAML 头看起来不起眼但直接影响使用体验。description写得好不好决定了 AI 在模糊触发时能不能正确匹配到你的命令argument-hint写得好不好决定了你敲命令时会不会一头雾水。我的建议是--- description: 生成数据库迁移方案包含回滚脚本和风险评估 argument-hint: [迁移描述如给 users 表增加 age 字段] ---description必须是一个完整的句子说清楚命令做什么argument-hint要给出示例让人一看就知道该往里面填什么。这两项信息写清楚命令的可用性会提升一个台阶。另外如果你在团队里共享模板命令文件的头部还应该加上owner字段标明维护者。模板也是代码需要有人负责演进和维护否则过半年就变成了无人维护的僵尸模板。6. 从个人模板到团队模板库落地推进的几条建议最后聊一聊如何把模板体系从个人玩具变成团队资产。很多团队引入 Claude Code 后卡在最开始的配置不一致上每个人用自己的命令、自己的规范代码风格肉眼可见地飘忽起来。我建议的推进路径是先由一个人或一个核心小组设计初始模板库不要全员自由发挥。模板库是约定的载体约定的第一原则是有人负责统一设计。模板库随代码仓库走纳入代码评审范围。任何人改动 CLAUDE.md、命令模板、技能包都必须过代码评审理由和代码变更一样这会影响团队所有人的 AI 协作行为。新成员入职时把阅读模板库作为熟悉项目的必做环节。很多人觉得看 CLAUDE.md 是在浪费时间但实际上它包含了项目最精炼的协作规范比翻几百页文档高效得多。每季度做一次模板审计删掉无效命令、合并重复技能、更新过时规范。模板不进则废定期清理和功能迭代一样重要。我自己在实践中最大的体会是**模板体系的成功与否不取决于写了多少命令和技能而取决于它是否真正嵌入了团队的工作流。**一个只有 5 条命令但每天都在用的模板库比一个 50 条命令但从没人触发的模板库有价值得多。如果你刚开始搭建我建议从成熟场景入手代码审查、技术方案、发布检查清单这三个方向几乎适用于所有软件开发团队。跑通这三个场景之后再逐步扩展其他领域——测试报告生成、日志分析、架构决策记录、周报整理——每个场景经过验证确认值得固化成模板再动手写。不要追求一步到位让模板库跟着真实需求一起成长。我个人在写模板时还有一个执念每个模板都假设三个月后自己会忘记当时为什么这么写所以会在文件末尾加一小段设计意图说明。这不是给 AI 看的是给人看的——记录当初为什么定这个规则方便后续维护者理解取舍。半年后再看这些文字比代码注释更值钱。