大概三个月前，我把 Claude Code 从一个"偶尔拿来写点脚本的玩具"正式转成了日常主力编程搭档。这三个月里我最深的体会是：模型能力的上限，其实很少是瓶颈；真正决定它好用不好用的，是你有没有一套 claude-code-templates。我的意思是，把每次会话里都要重复交代的项目背景、目录结构、构建命令、代码规范、审查标准这些东西，提前写成模板，让 Claude 一进项目就自带记忆，而不是每次新开一个终端都"重新投胎"。这篇文章不是官方文档的复述，而是我自己整理模板库的完整记录——包括每一类模板解决什么问题、具体文件长什么样、怎么测试和同步，以及照着文档做却依然翻车的那几个坑。

这套东西适合谁？如果你是每天都会打开 Claude Code 的独立开发者，或者团队里想统一 AI 编程规范的技术负责人，那下文大部分内容可以直接抄作业。如果你只是偶尔拿它问个问题、写个一次性脚本，那先不用急着搭模板，等使用频率上来了再回来看不迟。模板这东西，本质上是在为高频重复劳动做投资。

1. 为什么我把 Claude Code 从"临时助手"变成了"团队规范执行器"

1.1 没有模板的 Claude Code，每开一个会话都是重新投胎

我印象最深的一次翻车，是接手一个新仓库后第一次用 Claude Code 改 bug。我花了大概两分钟在会话里粘贴 README、目录树、package.json 里的 scripts，然后才敢让它动手。结果它还是把项目的测试命令猜错了——我让它跑测试，它用了npm test，而那个项目实际是pnpm vitest run。全红的下拉日志刷了一屏，那一刻我意识到：问题不在模型，在我。

没有模板的时候，你做的其实是每天早上给一个新实习生做入职培训。你讲得越细，它干活越像样；你讲得越糙，它就越会"合理猜测"。但上下文窗口是预算，不是无限的硬盘。你把背景信息全部塞进对话里，真正留给思考和改代码的空间就少了，到了长会话的中后段，模型甚至会把早先的指令忘掉、开始自由发挥。这是我在实际使用中反复确认过的规律，不是什么玄学。

所以模板的本质，不是"把提示词存起来"，而是"把项目的长期记忆从会话里剥离出去"。会话是短命的，模板是长寿的。你今天花十分钟写下的规范，下个月、明年，换一台机器、换一个队友，都还在那里起作用。这才是模板真正的杠杆效应。

1.2 模板化之后的工作流长什么样

现在我的流程是这样：git clone一个项目之后，如果它的根目录放了 CLAUDE.md，Claude Code 启动时就会自动读进去，我一句背景都不用交代。日常操作基本靠斜杠命令：/review审查改动，/commit生成提交信息，/pr写 PR 描述，/test跑测试并循环修复。这些命令文件本身就是模板，我可以把团队规范、审查清单、输出格式全部写死在里面。

这带来的改变是双重的。第一重是省时间：原来每次写提示词平均要花三五分钟，现在敲两个字符加回车就完事，一天下来省下的时间非常可观。第二重是稳定：同一套命令，今天跑和下周跑、小明跑和我跑，结果的口径是一致的。原来不同人让 AI 做事，相当于让同一批外包员工听不同项目经理的指令；模板化以后，至少大家都拿着同一份 SOP，谁指挥、结果都不会跑偏太多。

另外还有一个容易被忽略的好处：模板是强制性的记忆锚点。当团队里有人问"这个项目测试怎么跑""代码风格是什么"，你不用翻聊天记录，直接说"看 CLAUDE.md"或"用 /test 命令"就够了。模板把隐性知识变成了显性文件。

1.3 谁适合搭这套东西

我不建议一上来就追求大而全。根据我的观察，真正从 claude-code-templates 里吃到红利的是这么几类人：

• 每天高频使用 Claude Code 的独立开发者。个体开发者一般没有同事可以问，项目记忆全在自己脑子里，模板就是你的第二大脑。
• 三五个人的小团队。大家共享一套命令和 CLAUDE.md，审查口径、提交信息格式、测试流程都能统一，省掉大量"我让你跑测试你怎么用错了命令"的沟通成本。
• 开源项目维护者。贡献者来来往往，一套 CLAUDE.md 加几个命令，能让新手 contributor 第一次提 PR 就符合项目规范。

反过来说，如果你一个月才打开三次 Claude Code，每次都是问些孤立的问题，那模板库反而成了负担——维护它需要时间，而它的收益还没累积起来。我的建议是：先从最小集开始，只有当你发现自己连续三天在会话里重复粘贴同一段说明，才值得把它提炼成模板。

2. CLAUDE.md 模板：先把"项目记忆"固定下来

2.1 CLAUDE.md 的加载机制与设计初衷

CLAUDE.md 是 Claude Code 用来承载项目长期记忆的 markdown 文件。它的设计思路很朴素：把"你在每次会话开始时花五分钟口头交代的内容"变成一个静态文件，让模型在启动时自动读取。以我当前使用的版本为例，项目根目录的CLAUDE.md会在会话启动时自动加载，个人级别的~/.claude/CLAUDE.md则作为跨项目的基线记忆存在，任何项目下都会生效。

理解这个分层机制很重要：个人级的 CLAUDE.md 应该放"我这个人习惯怎么工作"，比如你默认使用 pnpm、提交信息喜欢 conventional commits、代码注释偏好中文还是英文；项目级的 CLAUDE.md 应该放"这个项目是怎么回事"，比如架构、命令、约定、坑。两者不要混。我见过有人把个人偏好写进项目文件，结果换一台机器、换一个协作者，别人读到的是一堆无关信息，既浪费上下文又误导人。

另外我用的版本还支持子目录级 CLAUDE.md，也就是packages/web/CLAUDE.md这种形式。它的加载是就近原则：当 Claude 的操作涉及那个子目录时，对应层级的 CLAUDE.md 会被读取，而不需要把整个 monorepo 的上下文全部塞进一个文件。这个机制对大仓库非常友好，后面我会专门讲。

2.2 一份够用的 CLAUDE.md 模板长什么样

先把模板放出来，这是我目前最常用的一份，精简过很多轮：

# 项目：XXX ## 一句话概览 这个项目做什么，给谁用，核心架构是什么。 ## 常用命令 - 安装依赖: pnpm install - 本地开发: pnpm dev - 测试: pnpm test -- --run - 构建: pnpm build - Lint: pnpm lint ## 架构约定 - 前端在 apps/web，后端在 apps/api - 状态管理用 zustand，禁止引入 redux - 所有对外接口走 /api/v1 前缀 ## 代码风格 - TypeScript 严格模式，禁止 any - 组件用函数式写法，样式用 tailwind - 提交信息遵循 conventional commits ## 已知陷阱 - 本地跑测试前必须先 pnpm generate 生成 client - Windows 下路径分隔符会导致 snapshot 失败，用 docker 跑

每一节都不是随便写的，我有明确的取舍标准：

关于"一行命令的写法"，我有个具体建议：命令后面最好带上实际参数，而不是只写pnpm test。因为模型对"怎么跑测试"的理解高度依赖你给的命令细节，pnpm test -- --run和pnpm test在带 watch 模式的项目里完全是两个行为。这类细节写清楚，模型一次跑对的概率会高很多。

2.3 子目录级 CLAUDE.md：给大仓项目做分区记忆

如果你在维护 monorepo，根目录一份 CLAUDE.md 往往不够。根文件写得太细，任何一次会话都会加载一大堆无关内容；写得太粗，模型进入某个子包时又拿不到关键信息。我的做法是：根目录只写全局约定和常用命令，然后在业务独立性强的子目录各放一份精简版。

举个例子，我有一个项目根目录 CLAUDE.md 里只写了"这是一个 pnpm workspace，前端在 apps/web，后端在 apps/api，测试统一用 vitest"。然后apps/web/CLAUDE.md里写它用了什么组件库、路由怎么定义、样式的规范；apps/api/CLAUDE.md里写接口设计规范、数据库迁移命令、认证方式。这样无论在哪个目录下发起会话，模型拿到的都是刚好够用的上下文，而不是一份膨胀的全仓说明书。

子目录级 CLAUDE.md 还有一个额外好处：它可以承担"模块交接文档"的角色。当我想让 Claude 只改前端某个页面时，根目录的大背景加上这个子目录的专项信息，命中率比单靠一份大文件高得多。这是我试过几种方案之后最终留下的配比。

3. 自定义斜杠命令：把高频操作压成一个词

3.1 命令文件的存放位置与命名规则

斜杠命令是 Claude Code 里我认为最被低估的功能。它的机制说起来很简单：你把一段提示词写进一个 markdown 文件，然后在会话里用/命令名触发，文件内容就会作为指令发给模型。以我用的版本为例，项目级命令放在.claude/commands/目录下，个人级命令放在~/.claude/commands/目录下。

命名规则很直接：文件名去掉.md后缀就是命令名。review.md对应/review，commit.md对应/commit。文件开头的 frontmatter 里可以写description，这样在会话里敲/时会出现命令列表和功能说明，团队成员一看就知道每个命令是干什么的。这一点千万别省，没有 description 的命令列表就是一排天书。

我的摆放习惯是：跟项目强相关的命令放项目目录里（比如某个仓库特有的发布流程），通用于所有项目的命令放个人目录里（比如 /review、/commit）。这样换项目时，通用命令依然可用，项目命令也不会污染其他仓库。如果你在团队里共享，那项目级命令通常跟着 git 仓库走，新成员 clone 下来就有了。

3.2 五条我每天都在用的命令模板

我目前个人目录里长期维护的命令有十七条，但真正每天高频触发的其实是这五条：

先说最重要的/review。这是我最常让 Claude 干的活，命令文件长这样：

--- description: 审查当前分支的代码改动 argument-hint: [可选：指定文件或范围] --- 你是一位资深代码审查者。请审查当前分支相对 main 分支的改动。 审查重点： 1. 正确性：逻辑是否有边界问题、并发问题、空指针风险 2. 安全：是否存在注入、越权、敏感信息泄露 3. 性能：是否有明显的低效实现、不必要的重复计算 4. 可维护性：命名、抽象层次、重复代码 输出格式： - 按严重程度分级列出问题（P0/P1/P2） - 每个问题给出文件位置和具体修改建议 - 最后给出总体结论：通过 / 修改后通过 / 不通过 $ARGUMENTS

这个模板的核心是两件事：第一，明确审查维度，否则模型只会泛泛地说"代码很清晰，没什么大问题"；第二，规定输出格式，让它给我的结果是可以直接贴进 review 评论里的东西。

再看一个/commit：

--- description: 根据 diff 生成符合 conventional commits 规范的提交信息 argument-hint: [可选：补充说明] --- 查看当前工作区和暂存区的 git diff，生成一条提交信息。 要求： - 使用 conventional commits 格式（feat/fix/docs/refactor/test/chore） - 主题行不超过 50 个字符 - 必要时补充正文，说明为什么这样改 - 只输出提交信息本身，不要多余解释 $ARGUMENTS

这里有个容易被忽略的细节：命令里写了"只输出提交信息本身"。不加这句话，模型经常会给你附带一段"这是我生成的提交信息"之类的说明，你还得手动删。这种"声明输出边界"的写法，我后面几乎每个命令都会用，效果立竿见影。

/test命令我稍微做了点差异化：它不只是跑一下测试，而是让 Claude 在测试失败时循环修复，直到稳定通过。但为了防止它陷入死循环，我给它加了一条硬性边界——同一问题尝试三次仍失败就停下来汇报，并列出怀疑点。这个"止损线"对长任务特别重要。

3.3 参数、变量与模型配置

斜杠命令不是死的。我用的版本支持在命令里使用$ARGUMENTS变量，也就是你在命令后面输入的参数。比如/review src/utils/parse.ts，$ARGUMENTS就会被替换成src/utils/parse.ts，命令随即变成"只审查这个文件"。这让一条命令既能处理"全量审查"，又能处理"定点审查"。

frontmatter 里除了description，还可以配置一些行为选项。以我用的版本为例，argument-hint用来提示用户在命令后输入什么参数，model可以用来指定这条命令走哪个模型。比如 /review 这种长上下文高难度的任务，我会让它用更强的模型；而 /commit 这种轻量任务，用默认模型就够了，速度还快。

有一点要提醒：Claude Code 迭代很快，不同版本的 frontmatter 字段名可能有差异。我自己的习惯是每升级一次版本，就花十分钟跑一遍所有命令，确认没有报错或行为变化。这个习惯后面会在测试章节再展开。

4. 进阶玩法：把模板组合成完整工作流

4.1 一条命令完成"改代码 + 补测试 + 更新文档"

很多人的第一反应是：既然模板这么好用，那我写一条"超级命令"，让它一口气完成"改代码、补测试、更新文档"行不行？我试过，结论是：不行，不要这么干。

原因在于，步骤越多的指令，模型越容易把后面的步骤当成"可选项"。它改完代码后经常会觉得"补测试有点麻烦，而且我改得挺稳的，跳过吧"，或者"文档更新不着急，先给你看看代码"。这是我在实际使用中反复踩过的坑。长链条指令看着高效，实际执行率极低。

我现在的工作流是拆成三段，每个命令只负责一个明确可验证的交付物：

1. 先下任务指令（可以是普通对话，也可以是一个 /implement 命令），让 Claude 完成代码改动；
2. 然后跑/test，专门处理测试，失败就修，直到通过；
3. 最后跑/docs，让它根据 diff 更新相关文档。

每一步的输出都是可检查的，哪一步出问题就盯哪一步。虽然看起来要多敲几次命令，但整体成功率和可调试性比"一条龙"高一个量级。尤其是当你让 AI 干活的时候，"把一个大任务切成可验证的小步骤"永远是对的。

4.2 用模板统一 PR 描述与 Review 口径

PR 描述是另一个非常值得模板化的场景。我见过太多 PR 只有一句"fix bug"，审阅的人根本不知道改了什么、为什么改。用命令模板把结构固定下来，这个问题基本就消失了。

我用的/pr命令长这样：

--- description: 根据当前分支与 main 的 diff 生成 PR 描述 argument-hint: [可选：补充背景信息] --- 根据当前分支与 main 的 diff 生成 PR 描述。 必须包含以下章节： 1. 改动背景：这个 PR 解决什么问题，为什么现在做 2. 变更内容：按模块列出核心改动，说明每个改动的目的 3. 测试验证：列出已执行的测试命令和结果 4. 影响面：这个改动会影响哪些模块/服务，是否有兼容性风险 5. 联调事项：需要人工验证的场景 语言：中文，简洁直接，不要渲染成营销文案。 $ARGUMENTS

它的价值在于让模型把审查者关心的信息都覆盖到，而不是自己挑着写。配合前面那个 /review 命令，一个负责产出、一个负责检查，两者口径对上了，团队协作会顺畅很多。

除了 PR 描述，我还维护着一个代码审查的 checklist 模板，单独放在.claude/commands/review-checklist.md里。它本质上是一份"团队审查规范"，任何负责 code review 的人都可以在会话里调用，确保大家审查时关注同样的维度。这个文件不需要很长，重点是明确红线——比如"禁止 any""禁止在循环里发请求""敏感信息必须走环境变量"这类团队硬规则。

4.3 模板与 Hooks 的联动

模板不只是提示词文件，它还可以跟 Claude Code 的 Hooks 机制联动，让规范从"建议"变成"强制"。以我用的版本为例，项目根目录的.claude/settings.json里可以配置 hooks，它会在特定事件发生时触发外部脚本或命令。

我目前用得最多的是两种。第一种是 PreToolUse 拦截：比如在 Bash 工具执行前检查命令，如果包含git push --force这类危险操作就直接拦截并提示。第二种是 PostToolUse 收尾：比如在编辑工具修改文件后自动跑一次格式化和 lint 修复。

举个例子，我的 settings 里配置了一个简单的 hook，让 Claude 在修改代码文件后自动执行pnpm lint --fix。这样模型生成的代码无论格式如何，落到磁盘上时已经被统一过一遍，人工审查时不用纠结缩进和分号。这个能力把"模板里的风格要求"变成了"系统级的执行动作"，可靠性完全不一样。

这里我想强调一个认知：模板告诉模型"应该怎样"，Hooks 保证"实际怎样"。两者配合，才能形成闭环。只写模板不做 hooks，遇到模型偷懒、跳过步骤的情况你依然要人工干预；只配 hooks 没有模板，模型不知道该往哪个方向写代码。我的配置顺序是先写命令模板，再为最关键的规范加 hooks 兜底。

5. 我的模板仓库目录设计与版本管理实践

5.1 推荐目录结构

模板积累多了，管理方式就得跟上。我目前把整套 claude-code-templates 放在一个独立 git 仓库里，整体结构是这样：

claude-code-templates/ ├── README.md ├── commands/ │ ├── review.md │ ├── commit.md │ ├── pr.md │ ├── test.md │ └── onboard.md ├── skills/ │ ├── frontend-debugging/ │ │ └── SKILL.md │ └── api-design/ │ └── SKILL.md ├── claude/ │ ├── CLAUDE.md # 项目级通用模板 │ └── user-CLAUDE.md # 个人全局模板范本 ├── scripts/ │ ├── install.sh # 一键安装到 ~/.claude │ └── sync.sh # 同步到具体项目 └── examples/ └── sample-project/

这个结构不是一次到位的。最开始我只有一个 commands 目录，后来发现有些"技能"不是简单的单次命令，而是一套带步骤和参考文档的方法论，就加了 skills 目录；再后来为了让新机器能快速恢复环境，才加了 install.sh。每加一个目录，都是因为某个真实需求反复出现。

关于命名，我的原则是名词用项目相关词，命令用动词。命令文件review.md、commit.md一看就知道干什么；而 skills 目录下的文件夹用场景词，比如frontend-debugging，因为一份技能往往包含多个操作步骤和配套说明。命名这东西没有标准答案，但保持一致性会让整个库好维护得多。

5.2 用 git 管理模板：变更记录与团队同步

模板既然是"项目记忆"和"团队规范"，它就应该是代码的一部分，走版本管理。我把它放在独立仓库里，每次改动都写清楚 commit message，打 tag 标明版本。等模板库稳定下来后，团队可以直接 fork 或者 clone 这个仓库作为起点，比每个人各自维护一套散落的文件强太多。

安装脚本install.sh做的事情很简单：把 commands 目录下的所有文件复制到~/.claude/commands/，把 claude 目录里的两个文件放到对应位置，再在终端打印一份使用说明。为什么用复制而不是软链？因为软链会让每个新项目都读到同一份实时文件，改错一个命令会影响所有项目；而复制能把版本冻结住，测试通过后再手动升级。对我这种追求稳定的用法来说，复制比软链安全。

团队同步的场景，我建议用sync.sh按项目拉取指定版本的模板子集，而不是把整个库塞进每个仓库。大多数项目其实只需要其中两三个命令，全量同步会让项目里出现一堆用不上的文件，反而增加了新人的认知负担。

5.3 模板的测试方式：golden prompt 回归

模板改多了以后，最大的风险不是语法错误，而是"行为漂移"——你以为这个命令会输出 A 格式，实际上新版提示词改完后偷偷变成了 B 格式。为了解决这个问题，我把提示词当成代码来测。

具体做法是维护一个examples/sample-project小仓库，里面放一个最简单的 API 项目，包含几条有代表性的业务逻辑和对应的测试。每次修改模板后，我就在这个 sample 项目上依次跑一遍所有命令，检查输出是否符合预期结构。比如 /review 是否分 P0/P1/P2 输出、/commit 是否只输出提交信息、/pr 是否包含五个章节。这份检查清单写在 README 里，跑一次五分钟，能挡住绝大多数回归。

这个方法听着笨，但它解决了一个真实痛点：提示词的微小措辞变化，可能不会立刻报错，但会改变模型行为。不测试、凭感觉改模板，到线上才发现行为漂移，那时候排查的代价已经很大了。我现在任何模板改动，哪怕只是加了一句话，都会跑一遍 sample 项目。这个习惯我很推荐你养成。

6. 踩坑实录：模板越多，翻车越多的三种典型场景

6.1 情景一：CLAUDE.md 写成一本书，上下文被塞爆

模板的第一个坑，就是我前面提到的：贪多。我有一次把项目的完整架构文档、接口列表、历史决策记录全部塞进 CLAUDE.md，总共写了一百多行。结果模型的表现反而变差了——它会在决策记录里找"依据"，而不是基于当前代码直接干活；有时候还会把过时的决策当成现在的规范，给出完全不相干的建议。

上下文是一个有限预算，你塞进去的内容越杂，模型真正能"注意到"的就越少。后来我定的规矩是：CLAUDE.md 只放高频、稳定、直接影响行为的信息；低频或易变的细节绝不进主文件，而是放在docs/里，在 CLAUDE.md 中用一行说明"遇到数据库迁移问题时，先读 docs/database.md"。模型需要时才去读，不需要时不占上下文。

这个"按需加载"的思路，跟缓存分层的道理一样。不要把全部知识塞进内存，把大块内容放磁盘，用索引去指路。我的 CLAUDE.md 现在控制在六十行以内，每增加一行都要问自己：这个信息每个会话都会用到吗？如果不是，它就应该待在别处。

6.2 情景二：命令模板太"贪心"，一步干太多事

第二个坑是命令设计的问题。我最初写过一个/release命令，想让它一口气完成"跑测试、构建、打 tag、生成 changelog、推送"。执行了几次，几乎每次都在中间某个环节出岔子——要么测试失败了它还在继续构建，要么 changelog 生成到一半就停了，而且你还很难判断它到底卡在哪一步。

问题在于，命令模板里的每个步骤对模型来说都是"软约束"，它会在压力下自己决定优先级，跳过一些步骤。解决办法就是我前面讲的：职责单一。每个命令只负责一个可验证的交付物，步骤之间用我人工推进，或者在命令里明确写出"每一步完成后停下来等待确认"。

现在我写命令模板时会刻意检查一件事：这条命令是不是只有一个明确的成功标准？如果成功标准超过一个，就拆成多条命令或分阶段执行。比如 /release 被拆成了/build、/changelog、/tag三个命令，虽然多敲了几次键盘，但每一步都能验证，失败时也知道该看哪里。稳定压倒一切。

6.3 情景三：模板跟实际项目脱节，变成"过期地图"

最后一个坑，也是最隐蔽的：模板里的信息是有保质期的。项目换了构建工具、改了目录结构、升级了依赖，CLAUDE.md 和命令模板里写的命令可能已经失效，但文件还在那里。模型照着过期命令跑，自然会出错，而你不会第一时间怀疑是模板的问题，反而会怪模型不行。

我的对策有两个。第一，在所有模板文件底部加一行Last checked: 日期，每次验证通过就更新。日期是给人看的，也是给模型看的——至少能让使用者知道这份模板多久没被维护过。第二，每隔一两个月做一次"模板体检"：把 sample 项目升级到最新依赖，跑一遍所有命令和 CLAUDE.md 里的每条命令，凡是不符合现状的就地改正。

写模板这件事，到后期其实不是写的问题，而是维护的问题。它像一个文档库，超过三个月不更新就开始腐烂。我个人的体会是：宁可少写十份没用时看着很全的模板，也要保住五份每月都在用、状态始终最新的模板。质量不取决于数量，取决于它最近一次被验证过的时间。

最后再分享一个小技巧：给每个命令文件加一行Last checked日期，刚开始纯粹是自我提醒，后来发现团队协作时它还有另一个作用——大家看到日期超过三个月的命令，就会主动问一句"这个还准吗？"而不是默默信任。这个习惯帮我避免了好几次拿着过期模板白干半天的情况。模板是死的，维护模板的人是活的，只有持续照料，这套东西才能真正成为团队的长期资产。