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还有的人干脆每轮对话都靠 CtrlC / CtrlV 粘贴一段说明。结果是同一批人用同一个工具产出质量参差不齐。明明 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 - ORMPrisma - 测试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 命令模板的存储路径与 frontmatterCLAUDE.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 试试剩下的事情实践中会告诉你答案。