claude-code-templates 实践分享做了一段时间Claude Code相关的开发工作我最深的一个感受是很多人的用法还停留在“打开终端敲一句prompt等结果”的阶段完全没有把这套工具当成一个可沉淀、可复用的工程体系来用。结果就是每次对话都要重新解释上下文每次生成代码的质量波动很大项目一复杂就经常出现前后逻辑不一致的问题。真正拉开效率差距的往往不是模型本身而是你有没有一套适合自己的claude-code-templates。这套模板体系说白了就是三件事把高频场景固化成模板、把项目规则沉淀成配置文件、把常用操作封装成slash command。这篇文章我会从设计思路、核心细节、实操过程到问题排查把我的完整做法拆开讲一遍希望能给正在折腾Claude Code的开发者一些可以直接抄作业的参考。这套东西适合谁如果你正在用Claude Code处理实际项目感觉每次对话的上下文管理很累、生成结果不稳定或者团队里多个成员使用同一套代码库但AI的表现参差不齐那这套模板体系就是给你准备的。新手也可以看我会把基础概念也讲清楚。1. 整体设计与思路拆解1.1 模板体系要解决的核心痛点先聊一个最基础的问题为什么需要模板体系Claude Code虽然是对话式工具但它的工作模式更像一个“每次都要重新入职的工程师”。你给它描述需求它在对话窗口内理解上下文然后基于理解去改代码。问题在于对话窗口的上下文是有限的而且每次对话都是独立的。你今天上午让它写完一个模块下午再开一个会话让它更新另一个模块它对你的项目结构、代码规范、技术栈偏好一无所知。我最早踩过的坑是这样的让Claude Code帮我在一个Node.js项目里新增一个API接口它生成了CommonJS风格的代码但我的项目是ESM写的它用了项目里根本不存在的工具函数它完全不知道项目里已经有一个类似的接口可以复用。后来我总结了一下问题不在于模型能力而在于我没有在每次对话开始的时候把该给的上下文给全。模板体系解决的就是这个“上下文重置”的问题。它的思路很直白把那些每次都要重复交代的事情提前写好放在固定的地方让Claude Code在启动时自动加载或者通过一个简单命令触发加载。这样无论谁来用、什么时候用、用多少次AI拿到的“入职培训”都是完整且一致的。1.2 三类核心资产prompt模板、CLAUDE.md、slash commands我把整个模板体系拆成三个层次每个层次解决不同层面的问题第一层是提示词模板prompt templates。这层解决的是“同一类任务不同项目里怎么做”的问题。比如代码审查、写测试用例、排查bug、做安全审计这些任务的特点是流程相对固定但每次都要在prompt里写一堆要求和约束。把它们固化下来就能保证每次的执行标准一致。第二层是项目规则文件CLAUDE.md。这层解决的是“这个项目本身有什么规矩”的问题。技术栈是什么、目录结构长什么样、代码风格有什么要求、有哪些全局约定、哪些命令不要随便用——这些信息写进CLAUDE.mdClaude Code每次启动都会自动读。第三层是自定义slash commands。这层解决的是“如何用最少的输入触发最复杂的行为”的问题。你的模板体系再全如果每个模板都要复制粘贴一大段文字用起来也很烦。把高频模板封装成/command的形式敲几个字母就能触发体验会好很多。这三个层次组合起来就构成了一套完整的体系规则自动加载、模板随取随用、高频操作一键触发。1.3 为什么采用“渐进式分层”而不是“一个大文件”很多人第一次接触CLAUDE.md的时候容易走入一个极端把项目所有信息都塞进去恨不得写两千行。结果是什么呢Claude Code调用的模型在读取系统提示和项目规则时会占用大量的上下文窗口。规则太多太杂反而稀释了核心规则的重要性模型不知道该优先遵守哪条。我的做法是渐进式分层根目录的CLAUDE.md只写最核心、最不能违反的规则控制在30-50行以内具体到某个目录、某个模块的细节规则放在对应的子目录CLAUDE.md里按需加载再细碎的内容比如某个第三方API的使用约定、某段复杂逻辑的实现说明通过文档引用方式按需读取。这个思路跟做API设计有点像你不可能把所有接口文档都塞进SDK的初始化配置里而是提供核心配置、按需加载、动态查询三个层级。Claude Code的上下文窗口是有限的每一行字都在消耗算力预算所以规则的编排也要讲究优先级和可裁剪性。2. 核心细节解析与实操要点2.1 一个高质量模板的组成要素很多人以为模板就是一段写得比较详细的prompt这个理解不够准确。一个真正好用的Claude Code模板至少要包含这几个组成部分角色与目标定义。模板需要明确告诉模型“你在这里扮演什么角色、这次任务要达成什么目标”。比如代码审查模板不要只写“帮我审查这段代码”而是要先定义“你是一名资深Code Reviewer重点审查安全性、性能、可维护性三个维度输出问题清单按严重程度排序”。上下文注入规范。模板里要明确需要哪些上下文以及从哪里获取。是读取特定文件、查看目录结构还是需要用户手动补充这决定了模板的自动化程度。约束条件与禁忌列表。这是模板里最有价值的部分。比如“禁止修改非相关文件”“禁止引入新的第三方依赖”“代码风格遵循项目现有约定不混用两种风格”。没有这些约束生成结果就会自由发挥质量不可控。输出格式约定。要求模型以什么格式输出是代码块、表格还是发现问题清单固定格式的好处不只是好看更重要的是输出结果可被复用——你可以把审查结果直接塞给另一个脚本做二次处理。2.2 CLAUDE.md的渐进式分层实践CLAUDE.md是Claude Code的核心配置文件放在项目根目录下每次启动会话都会自动加载。我不推荐把它当成“垃圾桶”什么都往里面丢。给你看一下我这个项目的分层做法根目录的CLAUDE.md我只放四类内容。一类是项目定位与全局架构说明三五行讲清楚这个项目是做什么的一类是硬性技术约束比如语言版本、框架选型、不允许使用的库一类是全局规范比如命名风格、提交信息格式、测试要求一类是命令快捷入口告诉模型有哪些自定义命令可以用以及什么时候该用哪个。子目录级的CLAUDE.md则只关注局部内容。比如src/utils/CLAUDE.md就写这个目录里的工具函数有什么使用约定、哪些函数是废弃的、新增工具函数需要注意什么。Claude Code在读取文件时如果当前关注点在这个目录下会优先或额外加载这些规则。我自己在实际使用中比较满意的一个做法是把外部文档比如某个第三方SDK的对接文档、某个复杂模块的设计文档放在docs/目录在CLAUDE.md里用docs/xxx.md的格式引用。模型在需要处理相关任务时会自动去读取这些文档而不需要每次都在prompt里粘贴。这样既保持了上下文精简又保证了信息的可达性。2.3 参数化模板与slash command的实现细节Claude Code的自定义slash command是通过在.slashes/目录下放置markdown文件实现的。每个文件就是一个命令文件名就是命令名。用/加命令名就能触发。这个功能能把那些动辄几百字的模板压缩成一次敲击。具体来说/code-review这个命令我做成了参数化的形式支持languagepython和scopegit两个命名参数。它在执行时会先去读取git staged的代码然后按语言指定规则做审查。你可以看下这个示例--- description: 审查代码变更重点关注安全性和可维护性 argument-hint: language语言类型scope审查范围(git|files) --- 你是一名资深代码审查专家。你的任务是审查代码变更并输出结构化的审查报告。 上下文输入 - 审查范围请根据参数 scope 确定。如果是 git请查看当前git暂存区或最近一次提交的变更如果是 files请等待用户提供具体文件路径列表。 - 语言环境重点检查 language 参数指定的语言默认为项目中常见的语言。 审查维度按优先级排序 1. 安全漏洞注入、越权、敏感信息泄露、不安全的反序列化等 2. 性能问题明显的循环嵌套、不必要的大对象创建、N1查询等 3. 可维护性命名是否清晰、函数是否过长、是否存在重复代码 4. 一致性新代码是否遵循项目现有风格和约定 硬性要求 - 只报告真实存在的问题不要为了凑数而提无关紧要的小问题 - 每个问题必须给出严重程度致命/警告/建议、文件与行号、问题描述、修复建议 - 禁止输出空泛的评价比如“这段代码写得不错但可以更好” - 如果没有发现问题请直接输出“未发现需要报告的问题” 输出格式 使用Markdown表格输出按严重程度降序排列分为三个表格致命问题、警告问题、建议改进。这套实现方式参考了官方文档中关于.slashes目录和参数声明的设计markdown头部包含了命令描述和参数提示正文是完整的prompt模板。有了这个命令我在做代码审查时不再需要每次手写要求只需要指定语言和范围就够了。3. 实操过程与核心环节实现3.1 初始化模板目录结构这套模板体系说白了就是三件事把高频场景固化成模板、把项目规则沉淀成配置文件、把常用操作封装成slash command。整套体系的目录结构我放在下面你可以直接在项目里用# 在项目根目录或用户级配置目录下创建 mkdir -p .claude/slashes mkdir -p .claude/templates mkdir -p docs/ai-guides我用的是.claude/目录来统一存放所有AI相关的配置和模板这样比散落在各个地方好管理。你完全可以选择用.slashes/目录来放slash commands但有时项目里已经有其他工具占用了这个目录名为了避免冲突我最终采用的是.claude/slashes这个路径。目前Claude Code本身对这种结构的支持已经比较稳定。对应地CLAUDE.md的层级组织如下项目根目录/ ├── CLAUDE.md # 全局规则精简版 ├── .claude/ │ ├── slashes/ # 自定义slash commands │ │ ├── code-review.md │ │ ├── test-generator.md │ │ └── security-audit.md │ └── templates/ # 全量模板库作为知识库被引用 │ ├── pr-description.md │ ├── refactoring-plan.md │ └── api-design.md ├── src/ │ ├── utils/ │ │ └── CLAUDE.md # 子目录局部规则 │ └── api/ │ └── CLAUDE.md # 子目录局部规则 └── docs/ └── ai-guides/ └── third-party-sdk.md # 按需加载的外部文档3.2 完整的CLAUDE.md配置示例这里我给出一份相对通用的CLAUDE.md你可以按项目情况裁剪。这份文件里我刻意控制行数每一条都是硬规则不写废话# 项目全局规则 ## 项目概述 这是一个基于 TypeScript 的 Node.js 后端服务提供 RESTful API。 核心模块包括认证模块、订单模块、支付回调模块、用户中心。 ## 技术约束硬性规定 - 语言与运行时TypeScript 5.x Node.js 20.x禁止在新增代码中使用 JavaScript - 框架Fastify禁止引入 Express 或其他 Web 框架 - 数据库PostgreSQL Drizzle ORM禁止使用 raw SQL 拼接可使用参数化查询 - 不允许新增任何第三方依赖除非在需求中明确允许 ## 代码风格 - 所有文件使用 2 空格缩进字符串使用单引号 - 函数命名使用 camelCase类名使用 PascalCase - 所有新增的公共函数必须附带 JSDoc 注释 - 错误处理禁止静默吞掉异常empty catch block必须至少记录日志 ## 测试要求 - 所有新增业务逻辑必须包含单元测试 - 测试文件与被测文件同名放在 __tests__/ 目录下 - 使用 vitest 作为测试框架禁止新增 jest 测试 ## 常用命令 - /code-review对暂存区代码做安全与质量审查 - /test-generator为指定模块生成单元测试 - /security-audit对项目做依赖安全与配置安全检查 ## 外部文档 - 支付服务对接说明docs/ai-guides/payment-sdk.md - Redis 缓存约定docs/ai-guides/redis-conventions.md这份配置看起来不长但每一行都在约束模型的自由发挥空间。你可以对比一下如果没有这些规则模型可能为了某个小功能就给你引入一个新的npm包有了这些规则它就会知道“此处不应该引入新依赖”转而寻找复用方案。再补一份子目录的局部规则示例放在src/api/CLAUDE.md下# API 模块局部规则 ## 本目录职责 - 处理 HTTP 层的请求解析、参数校验、响应格式化 - 禁止在路由处理函数中编写业务逻辑业务逻辑必须调用 service 层 ## 接口设计约定 - 所有接口响应遵循 { code, data, message } 结构 - 分页参数固定为 page 和 pageSize分页响应包含 total - 新增接口必须包含参数校验推荐使用 zod ## 注意事项 - auth 中间件已在全局注册路由内不需要重复校验身份 - 已有的 /api/v1/orders 路由不要改动下游客户端依赖旧字段3.3 全量模板库的关键内容slash commands是给高频操作用的但你的模板资产远不止这几个命令。我把不常用但偶尔会用到、或者需要大篇幅详述的场景放在模板库里作为知识库。AI按需去读取这些模板文件的内容。这里挑两个典型的模板示例说明一下一个是PR描述生成模板不需要做成slash command因为不是所有人都在终端里提PR。但模板内容还是很有价值的你负责为代码变更生成高质量PR描述。上下文输入为git diff或变更文件列表。 生成内容 1. 变更概述用2-3句话说明这次变更解决的核心问题 2. 变更清单按模块维度列出每条包含文件路径和一个短说明 3. 测试计划列出已验证的测试项和未覆盖的风险点 4. 回滚方案说明如果出现问题如何快速回滚 约束 - 输出语言与现有提交记录风格一致 - 不编造未实现的功能不夸大变更影响 - 变更清单不超过10条超出部分按重要度截断另一个是API设计评审模板。当你在设计新接口或者改造旧接口时可以把接口定义内容输入进来让AI按模板维度帮你做评审。这个模板非常适合在动手写代码之前用可以避免设计上的一些坑你是一名API设计评审专家。用户会提供一个接口设计方案可能是文字描述或代码片段请从以下维度审查 1. 语义一致性是否符合RESTful惯例资源命名是否合理 2. 参数设计是否有多余参数是否有缺失的必选参数分页、排序、过滤是否完备 3. 错误处理错误码是否语义清晰是否区分了客户端错误和服务端错误 4. 安全性是否存在越权风险是否需要额外的权限校验 5. 兼容性如果是v2接口与v1的差异是否明确下游迁移成本是否合理 输出结构化评审报告每个维度给出结论通过/改进/重新设计 理由 修改建议。这两个模板不需要单独做命令但属于那种“用的时候粘贴过去就能生效”的类型平时整理好放在模板库里按场景取用就行。我把这套做法总结为一个原则高频、短平快的做成命令低频、需要深度的做成模板。3.4 从零组装一套可用体系实际初始化的时候我推荐按这个顺序操作每一步做完都可以先验证再往下走第一步搭骨架。把.claude/slashes、.claude/templates、docs/ai-guides这三个目录先建好然后写好根目录的CLAUDE.md。CLAUDE.md先写技术约束和项目概述两部分就够了其他内容后续逐步加。第二步做两个高频命令。挑你个人使用频率最高的两个场景做成slash command。对我这种后端开发者来说最高的两个就是/code-review和/test-generator。做完后在命令行里敲一下确认能正常唤起。你可以看一下下面这个test-generator命令的定义--- description: 为指定的模块或函数生成单元测试 argument-hint: target目标文件路径frameworkvitest|jest --- 你是一名测试工程师。根据参数 target 指定的文件生成对应的单元测试文件。 输入要求 - 如果用户没有提供 target请列出当前目录下的候选文件让用户选择 - 测试框架默认使用 framework 参数指定的选项未指定时使用 vitest 测试设计要求 1. 覆盖正常路径、边界条件、异常路径 2. 对外部依赖数据库、HTTP请求使用 mock不发起真实调用 3. 每个测试用例必须有明确的断言禁止无断言的测试 4. 测试命名使用 should_描述行为的格式 输出格式 - 包含完整测试文件代码使用 markdown 代码块包裹 - 在每个测试用例上方用 // Test: 用例描述 注释标明意图第三步补充局部规则和外部文档。这一步是迭代式的不是一蹴而就。我在实际使用中遇到AI反复犯同一个错误时就会把对应约束补进CLAUDE.md。比如有一次我注意到模型经常在Drizzle ORM查询里用select *我就在规则里加了一条“禁止select *必须明确列出查询字段”。这样下次它就不会再犯了。第四步建立维护循环。模板体系不是一次性工作。我给自己定了一个小习惯每两周花半小时review一下近期的AI使用记录看看哪些prompt是重复写的、哪些规则好像没什么用然后增删调整。模板是死的人是活的这套体系的核心价值在于它会随着你的使用越来越贴合你的工作习惯。3.5 敏感信息的处理方式模板和CLAUDE.md里绝对不能出现敏感信息这一点怎么强调都不过分。你可能会想把数据库连接串或者API密钥直接写进CLAUDE.md里让AI在生成代码时自动使用不是更方便吗千万别这么干。CLAUDE.md的读取权限、分享范围都不受控制一旦仓库被分享出去密钥就全泄露了。我的建议是所有敏感信息一律用环境变量或.env文件管理CLAUDE.md里只写“数据库连接信息存储在环境变量DATABASE_URL中代码中禁止硬编码任何密钥”。如果确实需要让AI知道某个服务的访问方式可以在本地通过交互方式提供给AI或者把带密钥的文档放在本地单独位置在CLAUDE.md里用绝对路径标注明确提醒模型“该文件仅限本地使用不要把其中内容写入生成结果”。4. 常见问题与排查技巧实录4.1 模板长上下文与窗口超限的平衡这是一个绕不开的问题。模板体系本质上是往上下文窗口里塞信息塞得太多窗口就爆了塞得太少效果不好。我遇到过一个场景某次做大型重构我把CLAUDE.md、子目录规则、外部文档、重构计划模板全部塞进去结果模型开始出现明显的行为退化——答非所问或者把前面的规则给忘了。排查出来的问题就是上下文超限。后来我强制自己遵守一条规则任何一次会话里主动注入的系统级内容不超过2000个token核心规则必须能在1000个token内说清楚。超长文档一律改为“按需读取”也就是放在docs目录里作为引用不直接粘贴内容。这样做之后模型的表现稳定了很多。如果你不知道怎么估token我提供一个土办法中文大约1.5个字符一个token英文大约4个字符一个token。CLAUDE.md全部内容控制在三千字左右是安全的。4.2 CLAUDE.md的规则为什么有时候不生效有几种情况会让你觉得“规则明明写了AI却当没看见”。第一种是规则写得太模糊。比如你写“代码风格要统一”这句话等于没说。模型不知道你的“统一”指的是什么风格。如果你写“字符串使用单引号、2空格缩进、禁止在条件语句中使用隐式类型转换”它就知道该怎么做了。第二种是冲突规则。CLAUDE.md里有两条规则打架模型就会困惑。比如一条说“所有公共函数都要JSDoc注释”另一条说“代码越简洁越好注释能省则省”。这种冲突没有明说模型就会随机选择一条来执行。我处理的方式是定期review规则看到有模糊表述或潜在冲突就立即修改。第三种是被会话内的用户指令覆盖。Claude Code的一个特点是会话内用户直接给出的指令优先级高于CLAUDE.md里的规则。这不是bug而是设计如此。所以如果你在某次会话里说了“不用管那些规则直接按我说的来”后续的行为都会被这个指令主导。排查的时候想想是不是自己先破了规矩。4.3 slash command无法识别或参数传错最常见的坑是目录路径不对。不同版本对不同目录的支持情况可能不同我遇到过把命令放在.claude/slashes下导致无法识别的情况排查之后确认版本对该路径的支持还不稳定。这个问题的排查思路先确认目录名拼写无误注意带不带开头的点再确认命令文件扩展名是.md最后确认YAML frontmatter格式正确——description是必填的不能偷懒省略。参数传递方面斜杠命令里的参数格式是keyvalue多个参数用分隔。比如/code-review languagepythonscopegit。如果你的参数值里含空格建议用引号包起来。这个问题在交互使用时不容易踩但如果你想通过脚本批量调用命令就需要注意转义问题。4.4 模板体系搭建后的效果量化最后聊一个怎么验证这套体系有没有用的问题。很多人搭建完模板体系后凭感觉说“好像效率高了一点”但具体高在哪、高多少说不清楚。我建议做三组简单量化第一组是重复性prompt占比下降。用模板体系后如果你还在每次对话里敲大段描述说明模板没覆盖到你的高频场景。第二组是代码审查缺陷率。我的做法是在每次/code-review后记录发现的致命问题数按周汇总。稳定的下降曲线说明整体的代码质量在提升。第三组是上下文重写次数。会话中因为上下文丢失、AI忘记约束而被迫重新描述需求的次数。理想状态下这个数字应该趋近于零因为模板体系的职责就是消除重复的上下文传递。这套体系其实就是一个不断积累的过程。做一次比较好做难的是做几次以后从实际使用中持续发现问题然后反馈到模板里。只要这个循环转起来了你会发现Claude Code的使用体验会发生质的变化——从“试一试看它能生成什么”变成“让它按我的预期稳定输出”。这也是我个人觉得这套模板体系最值得投入的地方。
