如果只用一句话总结我在实际工程里折腾claude-code-templates的感受，那就是：模板不是写给 AI 看的，是写给未来那个"又要重复解释一遍背景"的自己看的。我最早用 Claude Code 的时候，每个新会话都要花五六分钟重新交代技术栈、目录结构、编码规范，说的内容一模一样，AI 该犯的错一个没少。后来我把项目里沉淀出的提示词、CLAUDE.md、斜杠命令、甚至整个新仓库的初始化流程全部模板化，成体系地放进.claude/目录，才真正体会到什么叫"一次配置，长期收益"。
这篇东西适合谁？适合那些已经用上 Claude Code、但总觉得它"不够懂你项目"的人；也适合准备在团队里推广 AI 辅助开发的工程负责人。我会从 CLAUDE.md 的写法讲起，然后拆自定义斜杠命令、提示词模板的设计方法、整套脚手架模板怎么搭，最后把我踩过的坑一起说出来。整个过程里只讲我实际验证过的东西，你拿过去就能改着用。
1. CLAUDE.md 模板：给 AI 一份"入职手册"，而不是产品简介
1.1 为什么很多人的 CLAUDE.md 写了跟没写一样
我见过太多团队直接把 README 换个名字就当成 CLAUDE.md 用。里面写着"本项目是一个基于 Vue 3 + TypeScript 的后台管理系统，使用 Pinia 管理状态，Element Plus 作为 UI 库……" 这没错，但基本没用。因为 AI 读完这种简介，只知道项目里有什么，依然不知道该怎么干活。
真正的 CLAUDE.md 要回答的是下面这类问题：
- 改一个接口时，是先改类型定义还是先改 mock 数据？
- 提交代码时，commit message 应该用什么前缀？
- 写测试的时候，是优先补单测还是补集成测试？
- 某个目录是不是禁止手工修改、只能由代码生成器产出？
这些问题 TECHNICAL 背景完全不同，但有一个共同点：它们在每次会话里都会被反复问到。你不写清楚，AI 就会用它的"通用常识"来猜，猜出来的东西可能在语法上完全正确，但放在你的项目里就是不合规矩。
我自己有一个很直观的对比：某个支付模块的老仓库，没写 CLAUDE.md 时，AI 生成的新增接口总是忘了在事务里处理回调，代码能跑但资金对不上账。后来我把"涉及支付流程的修改必须使用@Transactional，必须在 try/catch 里显式处理退款失败"写进 CLAUDE.md，同样需求再让 AI 做，一次就对了。
所以 CLAUDE.md 的第一原则是：把"你希望 AI 怎么做决策"写成规则，而不是把"项目有什么"写成介绍。内容定位错了，写多长都白搭。
1.2 一个可复用的 CLAUDE.md 骨架
我现在的新项目都用一个固定的 CLAUDE.md 骨架，大概 60 到 120 行，按优先级分成几个区块。写给你看一下结构，你可以直接抄回去改成自己的。
# 项目基本信息 一句话说明项目业务目标：这个系统解决什么问题，核心用户是谁。 当前主要技术栈与关键版本：框架、语言、包管理器。 本地开发常用命令：安装依赖、启动、跑测试、构建、代码检查。 # 目录结构与修改禁区 - src/ 下各目录职责一句话说明 - 禁止手工修改目录：`src/generated/` 内容由 `npm run gen` 生成 - 涉及跨模块改动时，必须同步更新 `src/types/api.ts` 中的类型定义 # 编码规范与做事标准 - 新代码遵循项目的 ESLint + Prettier 配置，提交前跑一遍 - 后端接口统一返回 `{ code, data, message }` 结构 - 新增异步操作必须考虑错误处理，不允许裸 promise - 单元测试用 Vitest 写，文件名后缀统一 `.test.ts` # 高频业务规则 - 订单模块：状态流转只能按 待支付 -> 已支付 -> 已发货 的路径进行 - 用户模块：删除用户是软删除，字段 `deleted_at` 置位 - 权限模块：新增接口必须在权限表中登记权限点 ID # 常用命令与脚本 - `npm run dev`：本地开发，默认端口 5173 - `npm run generate:model`：根据数据库表结构生成模型文件 - `npm run check`：先跑类型检查再跑 lint，合入前必须通过这个骨架的关键在于：每条规则都写得像一个"可执行命令"，而不是一个模糊建议。比如说"注意代码质量"就没用，但"提交前跑npm run check，失败不能提交"就是 AI 能直接执行的指令。框架类的规则给一两条最核心的就够，最忌贪多。
我还喜欢在 CLAUDE.md 里放"角色定位"一小段。比如"你是一个精通该支付系统的资深后端工程师，当需求描述模糊时，先列出你理解到的三种可能，再选最合理的一种继续，不要直接动手"。这会让 AI 在最容易跑偏的地方停下来问一句，省掉后面大段返工。其实这就是在给 AI 设定一个"高年资同事"的人设，很多上下文问题它会自己补上。
1.3 全局配置与项目配置的分工
CLAUDE.md 可以放在两个层级，一个是用户级（通常在~/.claude/CLAUDE.md），一个是项目级（仓库根目录的./CLAUDE.md），两个文件会合并加载，项目的配置会覆盖或补充全局配置。这个机制特别适合分离"个人喜好"和"团队事实"。
我在全局配置里放的是和工作风格相关的东西，比如：
- commit message 统一用 Conventional Commits 格式
- 代码注释用中文还是英文（我习惯中文注释，但团队要求英文就按项目来）
- 通用代码风格偏好，比如"函数超过 80 行就该考虑拆分"
- 不希望 AI 默认调用的工具列表，比如禁止在没有 README 的情况下直接猜 npm scripts
在项目配置里则放只对该仓库成立的硬性事实，比如上面 1.2 里的目录结构、业务规则、部署流程。这样我切到任何一个项目，全局偏好会在，而每个项目的细节各自维护，互不污染。
一个小技巧：如果你在团队里推这套东西，全局 CLAUDE.md 不要强制统一，因为每个人的工作习惯不同。但项目级 CLAUDE.md 一定要让全员共用同一份，而且写清楚"改这里要过 review"。它就是团队的 AI 协作规范，和.eslintrc是一个级别的文件。
2. 斜杠命令模板：把重复劳动变成一个 /review
2.1 没有命令模板之前的痛苦
CLAUDE.md 解决的是"AI 懂不懂项目"的问题，但还有一个更日常的痛：每次让 AI 做同一件事，都要打一长串提示词。比如做一次代码审查，我以前会输入：
"请对我本次改动的这几个文件做代码审查，重点看有没有内存泄漏、有没有并发问题、错误处理是否完善，输出按严重程度排序，并给出修改建议。"
复制粘贴次数一多就烦了，而且每次打的字还有细微差别，AI 的输出格式也跟着飘。后来我把这类高频动作做成了斜杠命令：/review。在对话框里输入这一条，AI 就会执行我预先写好的完整逻辑，输入输出都稳定。
实际上，Claude Code 的自定义命令机制就是在项目目录下放一个.claude/commands/文件夹，里面每个.md文件就是一条斜杠命令，文件名就是命令名。"把一段重复提示词存成文件"这个思路不难，但它带来的确定性收益非常大。
2.2 命令文件怎么放、怎么写
先看一个我项目里真实在用的review.md命令模板：
--- description: 对暂存区代码进行系统性审查 --- 你是一名高级代码审查员。请按以下步骤执行： 1. 执行 `git diff --cached --stat` 查看本次变更概览 2. 执行 `git diff --cached --name-only` 获取文件列表，找出新增或修改的源文件 3. 逐个阅读这些文件的关键改动，重点检查： - 并发场景下是否存在竞态条件 - 资源使用后是否正常释放（连接、文件句柄、定时器等） - 有没有直接把异常吞掉的 catch 块 - 新增公共接口是否缺少边界校验 4. 按「严重 / 中等 / 建议」三个级别输出问题清单 5. 每个问题必须给出具体文件路径和行号，并给出修改示例 本次需要额外关注的业务约束：$ARGUMENTS这个文件里的$ARGUMENTS是魔法变量，用户输入/review 重点看登录模块的 token 刷新逻辑时，后面那段话会自动替换到$ARGUMENTS的位置。这样命令模板本身是通用的，但每次审查关注点可以临时指定，不用改文件。
命令文件的组织方式上，我建议按场景分目录。比如：
.claude/commands/ ├── review.md ├── test-generate.md ├── changelog.md ├── pr/ │ ├── create.md │ └── update-description.md └── legacy/ ├── explain.md └── migrate.md这样命令会自动变成/review、/pr/create、/legacy/explain，语义清晰也不容易重名。目录层级不要太深，两层基本到顶，再深就很难记了。
有一点要注意：命令文件默认执行前会让用户确认。如果你确认自己的命令模板足够安全，比如只是读取文件或者生成文本，可以在命令前加!变成review!这种无确认执行。我一般只在很可信的只读命令上这么干，凡是会改文件、跑脚本的，都留着确认，不然 AI 自作主张改了状态后果很麻烦。
2.3 命令模板如何复用和组合
命令模板最好的用法不是堆数量，而是能组合。我现在的.claude/commands/目录里大概有二十来个命令，但日常翻来覆去用的核心命令不超过十个。真正让我觉得值得的，是几个命令连起来能覆盖一条完整工作流。
拿发一个 Pull Request 举例。我之前要先后让 AI 做几件事：跑测试、审查代码、生成变更描述。现在我把它们串成了/pr/prepare一条命令：
--- description: 提交前全套检查，生成 PR 描述 --- 按以下顺序执行任务： 1. 运行 `npm run check`，如果有失败，停下来报告失败内容，不要继续 2. 运行 `npx vitest run`，统计失败用例数 3. 对比 `git diff --stat`，确认变更范围 4. 基于以上步骤，执行代码审查流程，检查是否存在明显问题 5. 生成 PR 描述，包含：变更背景、主要改动点、测试情况、需要 reviewer 重点关注的区域 命令行格式：`pr 描述`这样一条命令把原本四步的机械操作压缩成一次会话。而且因为步骤一失败就停，不会出现"带着错误继续跑"的滑稽场面。
组合命令还有一个隐藏好处：命令本身变成了团队的流程文档。新同事想了解"提交代码前到底要做哪些检查"，不用翻文档，看一眼.claude/commands/pr/prepare.md就全明白了。这比 wiki 里躺着的流程说明不知道高到哪里去了。
3. 提示词模板设计：命令式、上下文、输出锚点
3.1 模板写不好会怎么死
CLAUDE.md 和斜杠命令本质都是提示词模板，但写提示词模板有很多容易被忽视的失败模式。我总结了三种最常见的"死法"：
第一种死法：太宽泛。比如"请审查代码"五个字，AI 完全自由发挥，输出质量全看运气。它可能只看了表面风格问题，真正的并发隐患一个没提。这不是 AI 不行，是你没给它聚焦的指令。
第二种死法：太啰嗦。一个命令里塞了七八个目标，还有大段背景故事，AI 读的时候前面指令被稀释，执行时经常漏掉后面的关键要求。上下文窗口是有限的，模板里的每个字都在占用 AI 的注意力，废话越多，关键指令越容易被忽略。
第三种死法：没有输出锚点。你让 AI"分析一下这段代码"，它回你一段情感充沛却没有结构的散文。你说得清楚还好，说不清楚就还得反问一轮。模板里如果没定义输出格式，AI 就会拿它在训练数据里最常见的格式来应付你。
所以我后来设计模板时，给自己定了一条规矩：每条模板至少解答三个问题——做什么？在什么条件下做？产出物长什么样？
3.2 三段式模板设计法
按这个思路，我用的模板结构固定成三段：
命令式开头：动词开头的一句话，直接说清要做什么。"审查""生成""重构""解释"都行，绝不用"请帮我看看能不能……"这种带商量语气的写法。指令越干脆，AI 越不会犹豫。
上下文与约束：包括输入来源（哪个文件、哪段 diff）、必须遵守的规则、禁止事项、如果条件不满足时的处理方式。这部分的每个句子都要能被执行，不要出现"注意安全""保证质量"这种不可操作的空话。
输出锚点：明确要求输出什么格式、分几个章节、需不需要给代码示例。最好连"如果没有发现问题就明确说'未发现严重问题'"这种兜底话也写进去，不然 AI 为了表现自己总会凑几条建议。
用一个通用公式表示就是：
[做什么] + [输入/范围] + [约束条件] + [输出结构] + [兜底行为]这五要素不一定每次全用，但动笔之前过一遍这个公式，能逼自己想清楚。我自己写模板时有个有趣的习惯：先写"输出锚点"，再倒推前面的指令和约束。因为输出结构是模板的心脏，它定了，前面要喂什么信息自然就清楚了。
3.3 三个可以直接抄的模板案例
我直接在项目里用的三个模板给你看看，都是踩过坑之后改出来的版本。
案例一：单元测试生成模板
为以下文件生成单元测试： 文件路径：$1 要求： 1. 仅测试该模块导出的公共函数，不测试私有函数 2. 覆盖正常路径、边界值、异常输入三组场景 3. 测试文件放在 `tests/unit/` 下，文件名以 `.test.ts` 结尾 4. 使用项目已有的测试框架和风格，禁止引入新依赖 5. 输出每个测试用例的命名和对应场景列表，再给出完整代码这里$1是位置参数，用户在/test-gen src/utils/format.ts时自动生效。很多模板失败都是因为让 AI"分析需求"，这个模板则直接给出了完整的方法论与路径。
案例二：旧代码逻辑梳理模板
解释以下模块的实现逻辑与调用关系： 文件：$ARGUMENTS 输出格式： 1. 模块职责一句话概括 2. 核心函数逐个说明：输入、输出、副作用 3. 被其他模块引用的位置列表（用 grep 结果） 4. 该模块中你认为可以重构的点，按优先级排序这个模板看起来简单，但它的价值在于第四条。单纯让 AI"解释代码"它只会复述；明确要求"给出可重构点排序"后，它才会带着审阅视角去读代码，输出立刻就不一样了。
案例三：变更日志生成模板
根据 git log 生成最近一次发布的变更日志： 范围：`git log $(git describe --tags --abbrev=0)..HEAD` 要求： 1. 按 feat / fix / refactor / docs / test 分类 2. 每条描述不超过 20 个字，使用祈使句 3. 将 commit hash 附在每条后面，格式为 (abc1234) 4. 输出标题 `## Changelog`，下面是分类列表这类模板有个共同点：输出锚点都非常具体。AI 生成完你几乎不用改格式，直接贴进 release note 就能用。
4. 项目脚手架模板：新项目开局，直接复制整套 AI 工作流
4.1 脚手架模板不只是一堆目录
如果说前面都在讲"怎么用模板让 AI 更懂当前项目"，那这一步就是"怎么把整套模板体系复制到新项目里"。我每次开新仓库，目录结构里必带一套.claude/配置，内容包括：
CLAUDE.md：基本信息、编码规范、目录结构commands/：团队通用的命令模板，比如 code-review、test-generate、changelogagents/：按场景拆分的子代理定义文件settings.json：权限配置，配合 hooks 使用
这听起来只是复制几个文件，但效果差别很大。以前我开新项目，AI 是从零开始认识项目的，头两天对话质量低到令人发指。现在开局就带CLAUDE.md和一套命令，AI 的表现直接跳到"入职半年"的水平，省掉的不只是时间，还有前期的挫败感。
4.2 用脚手架模板统一团队工作流
团队里推广模板，最大的难题不是写，而是分发和同步。我见过有人把模板往共享盘一扔，半年后项目里跑的还是初版模板，问题越攒越多。所以我把整套模板放在独立仓库里维护，和业务代码分开，理由很简单：
- 模板升级不影响业务仓库
- 团队里谁觉得命令不好用，可以直接提 PR 改模板仓库
- 新项目初始化时，从模板仓库拉一份下来即可
一个比较实用的同步方式是模板仓库里写一个初始化脚本，把模板目录复制到当前项目：
#!/usr/bin/env bash # init-claude-template.sh TEMPLATE_REPO_URL="git@example.com:team/claude-templates.git" TEMPLATE_DIR=".claude" if [ -d "$TEMPLATE_DIR" ]; then echo "已存在 .claude 目录，跳过复制" exit 1 fi git clone --depth 1 "$TEMPLATE_REPO_URL" /tmp/claude-templates cp -r /tmp/claude-templates/template "$TEMPLATE_DIR" rm -rf /tmp/claude-templates echo "初始化完成，记得按项目情况检查 CLAUDE.md 中的个性化配置"脚本做得糙一点没关系，关键是别手动一个个文件拷贝。手动拷贝最大的问题是：顺手改了几个文件，下次同步时冲突一堆，最后谁也不知道哪个版本是权威的。模板仓库 + 一份初始化脚本，能省掉大量维护成本。
项目级模板放到业务仓库之后，像 CLAUDE.md 这种文件还得随着项目变化持续更新。我用的检查办法有点笨但很好用：经常留意 AI 在对话里反复问哪些问题，只要一个类型的问题出现三次以上，就是该把它写进 CLAUDE.md 的信号。
4.3 模板、子代理与 hooks：更进一步的自动化
当模板数量多起来之后，我发现单纯靠一个 AI 在主对话里完成所有任务开始力不从心。比如既要写代码，又要 review 代码，还要做架构分析，一个上下文窗口里塞得太多，效果会互相干扰。这时候就需要拆子代理（subagents）。
子代理的核心思路是：把特定的指令模板封装成一个独立代理，在需要时才加载。它和普通命令模板的区别在于，命令模板是在当前对话里套用指令，子代理则有独立的上下文空间，可以在主对话之外做专门审查。举一个项目里的例子：我定义了一个reviewer子代理，只负责代码审查，不在乎生成新代码。这样主对话里的 AI 专注写业务，专门的质量检查交给专门的代理，互不抢占上下文，产出质量比我早期把所有任务压在一个对话里要高不少。
settings.json里的 hooks 则是另一层自动化。我目前用得最保守也最实用的是跑测试的 hook：每次往暂存区提交前，自动触发测试命令，失败的话把结果贴回对话，让 AI 自己看到错在哪。这个不吃性能，但对反馈闭环很有帮助。
不过自动化这块我强烈建议宁少勿多。hooks 一旦加上，每次对话触发都会消耗 token，还得承担误触发风险。开局阶段先把 CLAUDE.md 和命令模板用好，再看有没有必要引入 hooks。
5. 我踩过的坑：模板设计里最容易出问题的几个位置
5.1 CLAUDE.md 越长效果越差
模板刚建起来的时候，我一度很贪婪，什么规则都想往里写，项目级 CLAUDE.md 写到了将近 200 行。结果 AI 的表现不升反降，经常出现"前面说要 A，后面说不要 A"的指令冲突，AI 自己都懵了。
后来我把 CLAUDE.md 当成"代码质量重要文档"来管理，给自己定了一个非常硬性的标准：项目级 CLAUDE.md 超过 150 行就必须做减法。核心业务规则保留，那些一次性的、推导出来的细节全部从主文件里删掉，转移到相关模块的说明文档中。如果确实有大量需要 AI 知道的上下文，就把信息拆到子代理专属的提示词里，需要时才加载，而不是一股脑塞进主文件。
5.2 命令模板过度参数化
命令模板刚支持位置参数的时候，我像拿到新玩具一样，一个命令恨不得塞五个参数进去，$1、$2、$3全用上。结果预期中的灵活性没换来，倒是命令本身越来越难用。每次执行命令前都得想一遍"第一个参数是什么来着"，还不如直接手动输入提示词。
这是我的切身体会：命令模板的参数撑死两个，能不用就不用。大多数情况下，$ARGUMENTS一个捕获全部输入就够，位置参数只用在真正需要多段落分开解析的场景。模板的灵活性是设计出来的，不是参数越多越灵活，参数一多，使用者就被迫去记模板的接口签名，这和我们写代码时讨厌长参数列表是一个道理。
5.3 把模板当成一次性摆设
还有一类坑，是模板建好之后没人维护。我的判断标准是：一个模板如果已经连续三个版本没被改过，很可能它已经默默报废了。我会观察它实际还在不在用，对话里有没有人继承这个命令，反馈出来的效果对不对。
拿review.md来举例，我最初版本里没写"检查竞争条件"，因为当时项目是单线程的。后来项目接了一个消息队列，并发问题变成高危项，我第一次用 review 命令时发现了这个缺口，马上把它补进去。模板必须跟着项目一起演进，它不是建完就死的文档，而是活的工具链。
5.4 最终一个小技巧：从 AI 的问题反推模板缺陷
最后分享一个我到现在还在用的习惯。每次跟 Claude Code 对话，如果 AI 在我说完需求之后问了一句"你的项目是什么技术栈"或者"这个目录代表什么"之类的问题，我不会只回答它。我会立刻记录：为什么它不知道？是不是 CLAUDE.md 里没写？是不是写了但太隐蔽？
只要问题重复出现两次以上，我就把答案补进对应文档。坚持一两个月，CLAUDE.md 和命令模板会变得越来越精准。我会把 AI 反复问的问题当作一种测试反馈，反推模板哪里有缺口。这套"闭环维护"的思路远比一次写一个完美模板更实际，因为完美的模板根本不存在，但持续演进、持续贴近项目现实的模板，就是生产力本身。
