1. 为什么 Claude Code 需要一套模板体系
1.1 没有模板时，我遇到的三个真实问题
大概半年前，我开始重度使用 Claude Code 做日常开发，当时的状态是：每次新开一个项目，都要花好几分钟把技术栈、目录结构、编码规范、测试命令这些信息一点点喂给 Claude Code。项目少的时候还能忍，项目一多就完全扛不住了。最典型的一次，我在两个项目间切换，一个是 React + TypeScript 前端，另一个是 Python 后端服务，结果我给 Claude Code 描述上下文时，不小心把两个项目的约束混在了一起，它给我生成的代码里竟然出现了前端组件里 import requests 这种鬼东西。
第二个问题更隐蔽：就算我在对话里把项目背景说得清清楚楚，Claude Code 也记住了，但只要对话上下文一长，早期的约束就会被挤掉。到后面它开始"自由发挥"，输出风格逐渐偏离项目规范，比如我明明说了提交信息要遵循 Conventional Commits，它到第 40 轮对话之后又开始写"fix bug"这种完全没信息的提交信息。
第三个问题，也是让我下定决心做 claude-code-templates 的直接原因：团队的协作成本。我们小组四个人都在用 Claude Code，但每个人的用法都不一样。有的人在对话里口头描述项目约束，有的人把约束写进了 CLAUDE.md，还有的人干脆每轮对话都靠 Ctrl+C / Ctrl+V 粘贴一段说明。结果是同一批人用同一个工具，产出质量参差不齐。明明 Claude Code 自带模板机制，大家却没有把它用起来，这才是最亏的地方。
1.2 模板体系解决的不只是"少打字"
很多人以为 templates 就是省点事，少打几个字，这个理解太浅了。摸清楚之后，我认为 claude-code-templates 解决的是三个层面的问题。
第一层是"外部记忆"。CLAUDE.md 这类文件相当于给 Claude Code 外挂了一个项目百科，它加载项目时能自动读取这些内容，相当于你不需要在每轮对话里重新讲一遍"我们的项目是干什么的、用了什么技术、有什么坑"。第二层是"行为规范"。通过命令模板可以把团队约定、代码风格、提交流程这些软约束固化成硬指令，比如 /commit 命令统一按规范生成提交信息，团队里谁用结果都一样。第三层是"分工协作"。通过子代理模板，可以让不同的 Agent 各司其职——一个负责写业务代码，一个负责审查代码，一个负责跑测试，像团队分工一样清晰。
这个认知转变很重要。模板不是文档，模板是代码库里的"基础设施"。基础设施搭好了，后续所有和 Claude Code 的交互都是在这套地基上盖楼，盖得快不快、稳不稳，完全取决于地基。
1.3 适合谁用
如果你属于下面这几类人，这套模板体系值得花时间搞：
- 长期在同一项目上迭代，希望 Claude Code 的输出风格稳定一致；
- 同时维护多个项目，需要在项目间频繁切换上下文；
- 团队多人使用 Claude Code，希望产出规范统一；
- 老项目代码量大、依赖复杂，新人上手困难，想用 AI 辅助降低理解成本。
说实话，哪怕你只是一个人写自己的开源小项目，有一套清晰的模板也比每次在对话里啰嗦要强太多。
2. 模板的存放位置与加载机制：放在哪，影响非常大
2.1 CLAUDE.md 的三级加载结构
很多第一次上手的人以为 CLAUDE.md 只能放在项目根目录，其实它的加载机制比想象中灵活。Claude Code 会按作用域加载多个层级的 CLAUDE.md，我实测下来，主要分三级：
| 层级 | 路径 | 作用域 | 加载时机 | 典型内容 |
|---|---|---|---|---|
| 用户级 | ~/.claude/CLAUDE.md | 当前用户所有项目 | 每次启动时自动加载 | 个人偏好、通用编码习惯、常用工具说明 |
| 项目级 | <项目根目录>/CLAUDE.md | 当前项目 | 进入项目目录时自动加载 | 项目背景、技术栈、构建命令、约束规范 |
| 子目录级 | <子目录>/CLAUDE.md | 对应子目录及其以下路径 | 涉及该目录代码时加载 | 模块专属说明、局部架构决策 |
这里有个细节值得注意：用户级模板每次都会加载，项目级模板也会，子目录级模板只在 Claude Code 处理到对应目录下的文件时才会被引用。所以子目录模板适合超大仓库、模块边界清晰的场景，比如 monorepo 里一个目录管一个服务，各自有自己的规范和说明。
2.2 用户级模板与项目级模板的分工
我踩过的最大的坑，是刚开始把所有东西都塞进了用户级~/.claude/CLAUDE.md。当时觉得"反正每个项目都需要"，比如我要用 pnpm、要用 TypeScript、要写 Conventional Commits。结果跑了一段时间发现不对：不同项目的约束差异太大了，用户级模板里写"项目使用 pnpm"是通用的没问题，但写"项目部署流程是先构建再推送"就完全属于项目级的信息。如果硬塞进用户级，Claude Code 在 A 项目里会用 B 项目的部署流程，反而帮倒忙。
正确的分工应该是：
- 用户级模板放"你这个人"的偏好，比如你习惯的代码风格、你常用的工具链、你希望 Claude Code 默认采取的行为方式；
- 项目级模板放"这个项目"的约束，比如技术栈、目录结构、测试命令、部署流程、已知的坑。
如果你维护多个项目，用户级模板的收益最大，因为它一次配置、处处生效。项目级模板则每个项目单独写，可以视为该项目的一个 README 变体，只是它的读者不是人而是 Claude Code。
2.3 子目录 CLAUDE.md 的边界
子目录模板用得好的话非常香，比如我在一个大仓库里把前端、后端、脚本分成几个目录，每个目录下的 CLAUDE.md 只描述那块业务的上下文。Claude Code 处理到对应目录时，自动加载最短路径上最具体的说明，这对大项目控制上下文消耗非常有帮助。
但这里有个容易翻车的地方：子目录 CLAUDE.md 的作用域是"路径前缀匹配"，如果两个子目录的模板内容互相矛盾，或者子目录模板和根目录 CLAUDE.md 冲突，Claude Code 会优先采用更具体的那个，但有时候你根本分不清它到底用的是哪一层。我的建议是，子目录模板不要写和根目录模板重复的内容，只写增量信息。重复意味着冲突风险，增量才是子目录模板的价值。
提示：如果你不确定 Claude Code 当前加载了哪些模板，可以直接在对话里问它"你读取了哪些 CLAUDE.md？"，它能列出来。检查这个输出的习惯一定要养成，它能帮你快速发现配置是否生效，比对着文档猜快多了。
3. 一套可复用的 CLAUDE.md 模板设计
3.1 核心模板结构：从"项目自述"开始
写 CLAUDE.md 不是写作文，写清楚比写漂亮重要。我自己沉淀了一个比较通用的结构，分享出来供参考。这个结构我目前在多个项目里验证过，效果稳定。
# 项目：某服务名称 ## 项目概述 一句话说清楚项目做什么、给谁用、核心价值是什么。 ## 技术栈 - 语言：TypeScript（严格模式） - 运行环境：Node.js >= 20，包管理器 pnpm - 核心框架：Fastify - ORM：Prisma - 测试：Vitest + Playwright ## 目录结构 - `src/` 主业务代码 - `src/routes/` HTTP 路由，按业务模块组织 - `src/services/` 领域服务 - `tests/` 单元测试与集成测试 ## 开发命令 - 安装依赖：pnpm install - 本地开发：pnpm dev - 全部测试：pnpm test - 静态检查：pnpm lint ## 编码规范 - 遵循项目的 ESLint + Prettier 配置 - 组件和函数命名使用 PascalCase - 所有对外 API 必须有 JSDoc 注释 - 禁止使用 any，如确有需要先和 review 者确认 ## 关键约束 - 数据库迁移必须通过 Prisma Migration 完成，禁止手改数据库 - 配置文件统一放 `src/config/`，禁止硬编码环境变量 ## 常见任务 - 新增一个 HTTP 接口：创建 route -> 编写 service 逻辑 -> 注册 schema 校验 -> 补测试 - 修复 Bug：先写最小复现测试，再修复代码，再跑全量回归这个模板的核心思路是"用最少的信息让 Claude Code 不跑偏"。项目概述帮它建立全局认知，技术栈和目录结构帮它定位代码，开发命令让它能真实执行，编码规范和关键约束用来约束行为，常见任务则是把高频工作流的执行路径固化下来。
3.2 如何压缩上下文预算
上下文窗口是有限的资源，CLAUDE.md 写太长会直接挤占你用来和 Claude Code 对话、传递新信息的空间。这不是假设，是我实际测试过的情况：把一份 5000 字的 CLAUDE.md 放进去之后，对话响应质量明显下降，尤其是需要读大量代码文件的任务，它经常出现"记不住前面说了什么"的迹象。
那怎么压缩？我的原则有三个。
第一，每段最多三行。信息粒度要小，不要写长篇大论。第二，不写"为什么"，只写"是什么"和"怎么做"。CLAUDE.md 不是给人类看的科普文档，Claude Code 需要的是直接可执行的规则，你花三行解释"为什么采用 pnpm"，不仅浪费上下文，还可能让它发散。第三，凡是能从代码里推断出来的信息，不放模板里。比如目录结构，如果项目顶层就是 src、tests、scripts 这种常见布局，根本不用写，它扫一眼代码目录就知道了。只有当目录结构有特殊约定时才写，比如"所有业务子模块放在internal/下"这种非典型布局。
我实测下来，一个项目的 CLAUDE.md 控制在 60 到 80 行是比较舒服的范围。超过 100 行就得警惕了，可能你在把本该拆成命令模板或子代理模板的内容硬塞进来。
3.3 按项目类型微调模板
不同的项目，CLAUD.md 的侧重点完全不同。我维护了三套基础模板，分别应对前端、后端、CLI 工具，每个都经历过实际项目的打磨。
| 项目类型 | CLAUDE.md 侧重点 | 示例条目 |
|---|---|---|
| 前端应用 | 组件组织、状态管理、UI 风格 | "组件按页面目录组织，页面级组件放src/pages/" |
| 后端服务 | API 约定、数据库访问、鉴权规则 | "所有写操作必须校验 JWT，禁止未鉴权写入" |
| CLI 工具 | 命令结构、输入输出格式、错误处理 | "异常退出时向 stderr 输出错误并返回非零退出码" |
前端项目尤其要写清楚 CSS 方案和组件库，否则 Claude Code 很容易用错样式；后端项目最怕的是数据库操作乱来，所以相关约束要写严格；CLI 工具最核心的是参数设计和错误处理，这些不写清楚，生成的工具会非常难用。
我的建议是：先按自己最常接触的项目类型复制一份基础模板，然后跟着一个真实项目跑两周，期间把 Claude Code 每次理解偏差都记录下来，反向补充到模板里。这样迭代出来的模板才真正贴合你的实际场景，而不是纸面上好看。
4. 命令模板：把高频操作固化成斜杠指令
4.1 命令模板的存储路径与 frontmatter
CLAUDE.md 是静态说明，命令模板则把特定操作的完整流程封装成一个斜杠指令。创建方式也很简单：在.claude/commands/目录下放一个 Markdown 文件，文件名就是命令名。比如建立一个review.md，那么 Claude Code 中就出现了/review命令。
命令模板的文件结构由两部分组成：开头的 YAML frontmatter，以及主体的指令内容。frontmatter 用来声明命令的元信息，这个相当重要，直接决定命令何时可见、能调用哪些能力。
--- description: 对当前改动做代码审查，输出问题清单与修改建议 argument-hint: [可选] 指定审查范围，如文件名或模块名 allowed-tools: Read, Grep, Glob, Bash(npm test) --- 请对当前分支相比主干的所有变更进行代码审查。 审查重点： 1. 是否违反项目编码规范 2. 是否有明显的性能隐患或资源泄漏 3. 是否有并发安全问题 4. 测试是否覆盖了关键分支 输出格式： - 按严重程度分 High / Medium / Low 列出问题 - 每个问题必须给出文件路径和行号 - 最后给出可执行的修改建议注意allowed-tools这个字段：它限定了命令执行时 Claude Code 可以使用的工具，比如这里限制只能用读取类工具和跑测试的 Bash。这个限制的好处是防止命令在审查过程中乱改文件。
4.2 三个我常用的命令模板示例
第一个是/commit。生成规范提交信息是我用下来频率最高的命令，没有之一。
--- description: 按 Conventional Commits 规范生成提交信息 allowed-tools: Bash(git diff, git status), Read --- 执行 git diff 和 git status，理解当前工作区的改动。 然后按以下规则生成提交信息： - type 取 feat / fix / refactor / style / test / docs / chore - scope 取改动最集中的模块名 - subject 不超过 72 字符 - body 说明动机和影响面 - 如果存在破坏性变更，加 BREAKING CHANGE 说明第二个是/test. 写测试是我觉得 Claude Code 最值得固化的场景。只要是涉及新增功能的改动，我都希望通过这个命令自动补齐测试。
--- description: 为当前改动生成对应的单元测试和集成测试 allowed-tools: Read, Grep, Glob, Edit, Bash(pnpm test) --- 1. 用 git diff 查看当前改动 2. 识别新增或修改的公共函数 3. 为每个函数编写单元测试，覆盖正常路径、边界条件和异常路径 4. 如涉及接口变更，同步添加集成测试 5. 运行 pnpm test 确认所有测试通过第三个是/review。粗暴来说，它就是把我手里的人工 code review 清单转录给 AI 执行。
--- description: 对改动做一轮静态代码审查 allowed-tools: Read, Grep, Glob, Bash --- 按顺序执行： 1. 列出当前分支相对主干的变更文件 2. 逐个阅读，按严重程度记录问题 3. 重点检查：类型安全、资源释放、边界条件、并发、错误处理 4. 输出结构化报告，包含文件路径和行号这三个命令加在一起，覆盖了"改代码 -> 补测试 -> 提交 -> 审查"的完整周期。实测下来，每次代码审查至少能帮我多找出 2-3 个自己没注意到的问题，对质量提升是实打实的。
4.3 参数、多行输入与权限控制
命令模板支持参数传递。在命令主体中可以通过$ARGUMENTS拿到用户在斜杠命令后输入的所有文本，还可以用$1、$2拿按空格分隔的第几个参数。比如我先定义了一个命令叫fix，用户输入/fix src/service/UserService.ts 缺少空值校验，那么$1就是文件路径，$ARGUMENTS是完整字符串。
这里有个我常用的技巧：设计命令时尽量把参数设计成"补充说明"而不是"必填项"。也就是说命令主体先写好默认逻辑，用户不传参数也能跑，传了参数就当额外的约束条件。这样命令的容错性高很多。
权限控制是另一个容易被忽视的部分。allowed-tools里没有声明的能力，命令执行时就用不了。我强烈建议在模板块里先用最小化工具集，等确实需要更多权限时再放开。比如/commit命令里只开了 git 相关 Bash 和 Read，它就不能擅自调用 Edit 去改代码。这一步在多人项目里尤其重要，防止某个命令因为权限太宽而误操作。
5. 子代理模板：让 Claude Code 里多个角色协同
5.1 子代理的加载机制与配置结构
如果说命令模板是把"操作流程"封装成斜杠指令，那么子代理模板就是把"角色"本身封装成一个独立配置。子代理文件放在.claude/agents/目录下，每个 Markdown 文件代表一个角色。文件头部同样是 frontmatter，核心字段包括 name、description、tools、model。
--- name: debugger description: 擅长定位运行时错误、内存泄漏、死锁、并发问题，适合对复杂故障场景做根因分析 tools: Read, Grep, Glob, Bash, Edit model: sonnet --- 你是一位资深调试工程师。你的职责是： 1. 先复现问题，再定位根因 2. 复现需要最小化操作步骤，禁止随意扩大改动范围 3. 每给出一个结论，必须附上证据（日志、调用栈、代码行号） 4. 在提出修复方案之前，先分析三条候选方案并说明取舍理由description这个字段特别关键，因为主 Claude Code 会根据 description 来判断什么时候该启用哪个子代理。写得太宽泛，它会在不需要调试的场景也拉着 debugger 出来；太窄，则经常该出现时不出来。我的经验是把自己代入场景想一想：如果我只知道这些 description，能不能在正确的时候派这个代理上阵？
5.2 两个实际的子代理模板
我目前最常用的两个子代理，一个是 debugger，另一个是 frontend-developer。debugger 的配置刚展示过，重点说说 frontend-developer。
--- name: frontend-developer description: 负责 React 组件开发、样式实现和前端交互逻辑，适合新增页面和功能改造 tools: Read, Grep, Glob, Edit, Bash(pnpm) model: sonnet --- 你是前端开发工程师。你只负责前端相关任务，不处理后端逻辑。 React 开发规范： - 函数组件 + TypeScript 严格模式 - 样式使用 CSS Modules，禁止全局 class 污染 - 组件状态优先使用 hooks，复杂状态用 zustand - 所有异步操作必须处理 loading / error / empty 三态 - UI 细节遵循设计规范，色彩使用主题变量，禁止硬编码颜色 完成需求后，必须补充组件对应的 story 和基础测试。这个子代理的价值在于：我只需要说一句"新增一个用户列表页面"，它就会自动按既定规范产出组件、样式、测试和 story，而不需要我在主对话里反复强调 React 写法和样式方案。把约束从"每轮对话口头说明"变成"角色内置行为"之后，效率提升是非常明显的。
5.3 与命令模板配合的用法
子代理和命令模板不是二选一，它们可以配合使用。我最常用的一个组合是 /debug 命令，它本身只是一个调度器，负责唤醒 debugger 子代理来执行任务。
--- description: 对指定故障进行全流程根因分析，调用调试子代理执行深挖 allowed-tools: Read, Grep, Glob, Bash --- 调用 debugger 子代理处理以下故障： $ARGUMENTS 处理完成后，要求 debugger 输出： - 根因分析结论 - 证据链：日志、调用栈、代码行号 - 2-3 条候选修复方案及取舍依据 - 推荐的修复步骤实测中这个组合特别适合那种"现象明显、原因不明"的线上问题。用户传一段报错信息或者现象描述，debugger 会自己去翻日志、找代码、分析调用链，最后输出一份完整的分析报告。我拿到报告后自己再确认关键证据，整个排查链路清晰得多。
这里需要提醒一点：子代理的 model 字段可以指定不同模型。调试类任务我一般用 sonnet，因为它的推理速度更快、成本更低；遇到极复杂的架构分析，我才会切到更大模型。合理调配模型而不是样样用顶配，能省下大量 token 成本。
6. 维护模板时的常见坑与我的处理思路
6.1 模板越来越长，上下文越占越多
模板体系搭好之后，最常见的问题就是"内容膨胀"。尤其是命令模板和子代理模板，每发现一个新场景就往里加一段，过两个月回头看，一个 debugger 的配置可能已经写了上百行，里面一半是低频场景的冗余说明。
我的处理方法是给每个模板设"行数预算"。CLAUDE.md 整体 80 行以内，命令模板 50 行以内，子代理模板 80 行以内。超了就必须精简：能合并的合并，能删的删，如果发现一个模板里混着多个主题，就拆成两个模板。维护模板这件事本身也应该有一份"维护说明"，我把自己的维护原则写成了一条命令/tmpl，定期触发来检查所有模板的行数和有效性。
6.2 模板同步与版本管理
模板文件本质上是代码，就应该用代码的方式管理。我自己的做法是建一个专门的 dotfiles 仓库，把~/.claude/和所有项目的.claude/目录下的模板都纳管。每改一处，都走 git 提交，提交信息里写清楚改了什么、为什么改。这样不仅方便回溯，切换新机器时也能一键恢复环境。
对于团队场景，我更建议把模板放在项目仓库里，跟着主代码一起走。这样每个成员 clone 下来就自带模板，不需要额外同步。但也正因为模板会随代码分支变化，要注意合并冲突的问题。我的经验是模板文件尽量避免跨分支大改，实在要动就单独开 PR，并在描述里标注清楚影响面。
6.3 权限与自动化的边界
最后一类坑出现在"过度自动化"上。刚开始配置 hooks 时，我火力全开，设置了不少自动执行的动作，比如每次工具调用后自动跑格式化、提交信息不合规就自动改。听起来很美好，实际跑起来完全不是那么回事。自动格式化经常和手动改动的代码打架，自动修改提交信息更是会掩盖问题。后来我把 hooks 收敛到只做两件事：一是提交前检查格式，二是阻止明显错误的操作。凡是涉及"自动修改内容"的钩子，一律关掉。
权限边界也一样。allowed-tools和全局 permissions 尽量保持最小化，让 Claude Code 在需要权限时主动向你申请，而不是一次性把所有能力都放给它。尤其在命令模板和子代理模板里，权限宁可收紧再逐步放开，也不要在没有充分理解后果的情况下全量给。
我的切身感受是：claude-code-templates 不是一个配一次就能一劳永逸的东西，它需要跟着项目演进、跟着你踩过的坑不断维护迭代。但它的回报是长期的——越是维护得久，Claude Code 在项目里的表现越像一个真正懂这个项目的资深同事，而不是一个每轮对话都要重新介绍的临时工。如果你还在只用默认配置跑 Claude Code，今天就可以先建一个最简 CLAUDE.md 试试，剩下的事情，实践中会告诉你答案。
