1. claude-code-templates 这类仓库解决的其实是“AI 编码协作的出厂设置”如果你已经在终端里用 Claude Code 写过几天代码一定会有这种感觉它很强但“性格”有点飘。今天你让它做代码审查它给你列二十条小问题明天同一段代码它又觉得“整体不错”。你反复交代的规则换个会话它又忘了。这不是模型能力的问题而是缺少一套稳定的约定。claude-code-templates 这类项目本质上就是把“如何使用这个智能体”这件事从你的脑子里搬到文件里让它一开工就拥有统一的思维方式和行为边界。所谓 claude-code-templates不是特指某一个仓库而是围绕 Claude Code 沉淀下来的模板集合包括项目级的 CLAUDE.md、斜杠命令、Agent Skills、子代理定义、各类工作流提示词。你可以从网上下载别人整理好的模板回来改也可以按同样结构自己维护一套。最终解决的问题都一样让 AI 在第一次接触项目时就表现得像团队里一个已经入职三周的老同事而不是一个每次都要重新培训的实习生。这套模板适合三类人。第一类是刚接触 Claude Code 的开发者与其自己把提示词工程的坑挨个踩一遍不如直接借鉴一套成熟结构第二类是已经重度使用、但觉得每次会话都要重新交代上下文的用户第三类是团队负责人想把代码规范、审查标准、测试流程固化下来让每个成员包括 AI都按同一套规程办事。下面我会按从基础到进阶的顺序把模板的组织方式、书写方法、调试技巧和避坑要点完整讲一遍。1.1 模板解决的不只是“少打字”很多人以为模板就是“少打字”这低估了它的作用。斜杠命令确实能让你少敲几行字但 CLAUDE.md 和 Skills 真正改变的是模型的思考起点。一个没有模板的会话模型拿到任务后只能从通用知识出发猜测你的项目结构、代码风格、测试偏好有模板的会话模型在第一步就明确知道项目背景、技术栈、边界条件、禁止事项。这相当于给一个经验丰富但完全不了解你项目的顾问递上一份完整的背景简报效果差异是质的。更关键的是可复现性。没有模板时同一需求在不同会话里的输出质量波动很大有模板后模型的思考路径、输出格式、检查清单都被约束住了结果更稳定。对于团队协作模板还是一种“文档即代码”的文化规范写在哪里不重要重要的是 AI 和人都能看到同一份规范并且照章执行。1.2 模板和普通 Prompt 有什么区别普通 Prompt 是一次性的关掉会话就没了。模板是持久化的存放在固定目录里每次会话启动都会自动加载。普通 Prompt 是你对模型说“这次这样做”模板是让系统对模型说“每次都要这样做”。这听起来简单但操作机制完全不同模板不是靠复制粘贴而是靠目录约定、文件命名和上下文注入。所以学习模板的过程其实就是学习 Claude Code 的行为控制机制。1.3 也要认清模板的边界模板不是万能的。它只能影响模型的“默认倾向”不能保证每次输出都完美。代码写得不好、业务逻辑混乱模板救不了审查逻辑有漏洞模板也补不上。模板的真正作用是降低随机性、提高一致性和效率替你省掉每次重复交代的时间但最终的代码质量仍然取决于你提供的上下文质量和模型本身的水平。认清这一点你才不会对模板抱有不切实际的期待也不会因为一次输出不满意就全盘推翻模板的价值。2. 先看懂一套模板仓库的目录结构什么文件该放在哪儿在动手写模板之前建议先搞清楚 Claude Code 会主动读取哪些路径。Claude Code 的模板体系主要由指令文件、斜杠命令、技能目录、子代理目录四类构成。理解了文件系统的约定你的模板才算真正“注册”进了工具而不仅是十个文档堆在项目里。2.1 一张目录骨架一个典型的 claude-code-templates 仓库目录结构大致如下my-claude-templates/ ├── CLAUDE.md ├── .claude/ │ ├── CLAUDE.md │ ├── commands/ │ │ ├── review.md │ │ ├── test.md │ │ ├── refactor.md │ │ └── doc.md │ ├── skills/ │ │ └── security-check/ │ │ ├── SKILL.md │ │ └── scripts/ │ └── agents/ │ ├── api-designer.md │ └── test-writer.md └── shared/ └── prompts/ ├── pr-description.md └── commit-message.md2.2 每个目录各自负责什么CLAUDE.md是系统指令的核心入口Claude Code 会在进入工作目录后自动加载相当于给模型设定基础人格和项目背景。.claude/CLAUDE.md通常放不适合提交到公开仓库的、或者与具体项目绑定更紧的指令比如内部接口地址、部署路径、私有脚本用法。.claude/commands/目录存放斜杠命令每个.md文件对应一个命令。比如你建了review.md在 Claude Code 交互界面里输入/review就会触发对应提示词。这个机制相当于把高频操作固化成了工具特别适合代码审查、测试生成、提交信息整理这类重复度高的场景。.claude/skills/存放 Agent Skills 技能包以文件夹为单位每个技能包含一个SKILL.md入口文件还可以附带脚本和参考文档。技能和斜杠命令最大的区别是斜杠命令需要你主动输入触发而技能可以由模型根据任务描述自动判断是否启用。.claude/agents/用于定义子代理就是你可以临时委派给特定角色的模型实例比如“API 设计专家”“测试开发”。子代理有自己独立的提示词和工具权限会在主会话中并行或独立处理分派的任务。2.3 模板仓库和业务项目的关系你可以维护一个独立的模板仓库也可以直接把模板放在项目里用。独立仓库的好处是跨项目复用更新一次全局生效缺点是模板里的内容必须足够通用否则拿到其他项目里会“水土不服”。我的建议是分层管理全局用户目录里放通用规范比如代码风格偏好、通用审查清单项目仓库里放业务相关内容比如技术栈说明、目录结构、启动命令子目录级额外放模块相关的约束。这样既保证了复用性又避免了把团队隐私写进公开模板。3. CLAUDE.md所有模板的地基如果说斜杠命令和 Skills 是工具那 CLAUDE.md 就是地基。它是 Claude Code 每次会话都会固定读取的指令文件相当于模型行为的“宪法”。写不好 CLAUDE.md其他模板效果都会打折扣因为模型缺少统一的前提假设。3.1 三层加载顺序Claude Code 会按环境、项目和目录的三层结构加载 CLAUDE.md。用户主目录下的配置最先垫底适用于所有项目适合写个人偏好比如“默认使用中文回答”“提交信息遵循 Conventional Commits”项目根目录的配置覆盖用户级配置适合写项目相关的约束而项目子目录里的配置则只在进入特定目录时生效适合写模块级规范。理解这层加载顺序很重要否则你会遇到“明明写了规范为什么不生效”的问题。多数情况是配置放错了层级把只对某个模块有效的指令写在项目根目录或者把该放在用户目录的通用偏好写进了公共仓库结果所有协作者都被你的个人习惯绑架了。3.2 一份高可用 CLAUDE.md 的写入顺序我写 CLAUDE.md 时会固定按五个区块来组织角色与风格、项目背景、常用命令、约束与禁区、输出格式要求。角色与风格告诉模型它要以什么身份工作以及沟通偏好。项目背景是浓缩版的 README把技术栈、架构、核心目录结构写清楚。常用命令让模型在需要执行操作时不会抓瞎比如测试命令到底是npm test还是pnpm test。约束与禁区是必须重点写的部分比如“不要修改生成文件”“不要格式化第三方代码”。输出格式要求则控制回复的呈现方式比如代码审查用表格还是列表。3.3 一个可以直接落地的模板示例下面是一份适用于中型前端项目的 CLAUDE.md 骨架你可以直接拷贝后根据自己项目修改# 项目指令 ## 角色与风格 - 你是一名资深全栈工程师擅长从可维护性和可测试性角度提出建议。 - 使用中文交流代码标识符保留英文。 - 回答尽量精简先给结论再给解释。 ## 项目背景 - 技术栈Next.js 15 TypeScript Tailwind CSS。 - 数据层Prisma PostgreSQL。 - 目录结构app/ 放路由组件components/ 放业务组件lib/ 放工具函数prisma/ 放数据模型。 ## 常用命令 - 启动开发环境pnpm dev - 运行测试pnpm test - 类型检查pnpm typecheck - 代码规范检查pnpm lint ## 约束与禁区 - 严禁修改 app/api/ 下的鉴权逻辑除非明确说明。 - 不要直接改动 prisma/schema.prisma如需变更先同步数据结构分析。 - 生成文件不要手动编辑如果必须修改请在提交信息中注明。 ## 输出格式 - 代码审查意见用表格包含文件、行号、严重级别、建议。 - 给出重构方案时先说明改动范围再列出具体步骤。你可以看到这份模板几乎没有废话每条都是可执行的约束。写 CLAUDE.md 最容易犯的错误是写成抒情散文比如“请以用户为中心注重用户体验追求卓越”——这类话模型看了等于没看因为它没有可验证的标准。3.4 CLAUDE.md 的黄金比例理想状态下CLAUDE.md 的长度控制在 50 到 100 行之间太多会占据上下文空间导致回答变慢或忽略关键信息太少则覆盖不住关键约束。我见过有人把两千行的规范文档塞进去结果模型在长上下文中迷失重点关键的几条反而执行不到位。模板一定要做减法把你最在意的规则放进去其他“建议级”的内容宁可放在 Skills 里按需调用。还需要注意一点CLAUDE.md 中尽量不要写“你绝对不能”“必须永远”这类绝对化表述。绝对化指令过多会让模型变得僵硬在需要灵活处理的场景下表现反而变差。用“默认”“除非用户明确要求”“在以下情况下”这类限定语能给模型留出合理的判断空间。4. 斜杠命令模板把高频动作变成一句话CLAUDE.md 解决的是“默认行为”斜杠命令解决的是“按需执行”。它们的定位不同CLAUDE.md 是常驻内存的规则斜杠命令是输入即触发的一次性指令。对高频且流程固定的动作比如代码审查、编写测试、生成提交信息用斜杠命令非常顺手。4.1 斜杠命令的基本构成与触发方式在项目根目录创建.claude/commands/文件夹把每个命令写成一个独立的.md文件文件名去掉.md的部分就是命令名。比如review.md对应/reviewtest.md对应/test。文件的正文就是发给模型的提示词。第一行一般写一句简短的命令描述方便在斜杠菜单里预览。命令支持参数传递。$ARGUMENTS会把你在命令后输入的内容整体带入提示词$1、$2则对应第一个、第二个参数。例如你输入/review src/utils/format.ts命令文件里的$1就代表src/utils/format.ts。这个机制非常适合做“目标文件处理类”的命令。4.2 从零写一个 code review 命令我拿自己最常用的review.md举例路径是.claude/commands/review.md按 CR 清单审查代码变更对变更文件逐一检查。 1. 先运行 git status 和 git diff确定变更范围。 2. 结合 $ARGUMENTS 指定的文件范围过滤默认审查全部变更。 3. 审查维度包括功能正确性、边界条件、错误处理、命名、可测试性、安全性。 4. 输出格式为表格文件 | 行号 | 严重级别 | 问题说明 | 修改建议。 5. 严重级别分为必须修改、建议修改、可选优化。 6. 最后给出一个总体结论判断本次改动是否可以合并。这段命令的效果是你输入/review后模型会自动拉取 Git 差异按固定维度审查并输出统一格式的审查意见。相比在对话里手动说“帮我审查一下”命令模板的优势在于审查维度不会被遗漏也不会因为模型发挥失常漏掉安全类问题。4.3 带参数的命令怎么设计更多的场景需要指定范围。比如你只想审查某个文件或某个 commit命令可以这样设计审查指定范围内的代码变更。 审查范围$1 如果没有提供范围则自动用 git diff 获取全部变更。使用时输入/review src/apis/user.ts模型就知道只审查这个文件。这种参数化设计让同一个命令能适应不同粒度的需求而不用为每种情况单独建一个命令。4.4 我常在模板仓库里保留的命令清单命令名触发词用途关键参数代码审查/review按统一维度审查变更文件或范围测试生成/test为目标模块生成单元测试待测模块路径重构建议/refactor输出重构方案和步骤目标文件提交信息/commit基于变更生成规范提交信息无文档补全/doc为文件补齐注释和 README 片段目标文件API 设计/api生成接口设计草案接口描述这些命令模板都遵循同一个原则开头一句话描述任务中间列步骤末尾规定输出格式。步骤的价值在于让模型按顺序思考格式的价值在于让结果可比较、可复用。5. Skills 与 Subagents 模板让不同任务各就各位斜杠命令适合“你主动发起”的场景但有些能力更适合“模型自己判断是否需要”。Agent Skills 就是干这个的。而子代理则是更进一步把任务分派给一个拥有独立角色和工具权限的模型实例。5.1 先分清 Skill 和 SubagentSkill 更像一本“操作手册”。它封装了某类任务的执行方法、注意事项和参考样例模型在遇到相关任务时可以根据描述决定是否加载。比如你写了一个security-check技能里面包含常见漏洞清单、扫描步骤、修复建议那以后模型在处理涉及用户输入、HTML 渲染、SQL 拼接的代码时就有可能主动调用它。Subagent 则是“雇佣一个临时员工”。它有独立的名字、角色、提示词和工具权限通常由主模型调度也可以显式分派任务。它适合需要“并行思考”或“专职深度分析”的场景比如让一个测试专家子代理专门补测试同时你自己继续改业务代码。5.2 一个 SKILL.md 的标准模板Skills 目录结构以.claude/skills/skill-name/为单元入口文件必须是SKILL.md。文件头部用 YAML frontmatter 写元信息包括技能名称和描述正文写具体的操作指南。描述字段非常关键因为它决定了模型在什么情况下会想到调用这个技能。下面是一个 SKILL.md 的示例--- name: api-schema-validation description: 在修改 API 接口或新增接口时使用检查请求参数和响应结构是否与数据模型一致避免前后端联调时出现字段不匹配。 --- # API Schema 校验 ## 检查步骤 1. 定位相关路由文件和类型定义文件。 2. 列出新增或改动的接口逐一核对请求体、响应体字段。 3. 与数据库模型比对字段名和类型注意别名、可选字段。 4. 检查是否存在敏感字段被返回给前端的情况。 ## 常见问题 - 字段名命名不一致例如请求体用 snake_case接口响应用 camelCase。 - 时间字段缺省时区处理。 - 分页参数缺失默认值。 ## 输出格式 输出问题清单每个问题包含接口路径、字段名、问题类型、修改建议。你可以看到这个技能没有泛泛而谈而是把检查步骤、常见陷阱和输出格式都写清楚了。模型一旦加载这个技能执行路径就会稳定很多。5.3 子代理的 frontmatter 怎么写子代理文件是一段带元信息的 Markdown常见结构如下--- name: test-writer description: 负责为指定模块编写单元测试和集成测试尤其适合复杂组件和工具函数的测试。 tools: Read, Write, Bash model: sonnet temperature: 0.2 --- 你是一名测试工程师专注于提高测试覆盖率。在接到任务后先分析目标模块的结构再按以下步骤编写测试 1. 阅读源文件识别核心函数和边界条件。 2. 检查现有测试文件确定测试框架和风格。 3. 编写测试用例覆盖正常路径、异常路径、边界值。 4. 运行测试确保全部通过。frontmatter 里的 name 和 description 用于注册和调度tools 限定它能用哪些工具model 指定使用哪个模型版本temperature 控制创作随机性。不同版本的字段命名可能稍有调整使用前建议查一下对应版本的说明。核心思路是子代理的角色和边界越清晰主模型就越容易在合适的时机派活给它。5.4 什么时候用子代理而不是反复叮嘱如果某个任务复杂度高、又需要独立上下文比如“分析整个模块的设计并输出改进方案”用子代理就比在主会话里反复要求更合适。子代理不会被主对话里前后几十条消息带偏它能专注于单一目标。但也要注意子代理的上下文隔离是有成本的分派任务、传数据、汇总结果都需要时间简单任务用子代理反而更慢。我的经验是30 分钟以上的独立任务或者需要跨文件深度搜索的任务才值得动用子代理。6. 落地一份业务级 Workflow 模板模板的终极形态是“工作流”也就是把多个命令、技能和规则组合起来覆盖一个完整任务的生命周期。比如一次重构可能包含分析、改动、测试、审查四个阶段。把这些流程用模板串联起来就是你自己的工作流引擎。6.1 团队流程固化的思路假设你的团队要求所有代码合并前必须通过类型检查、单测和变更记录补齐你可以设计一套组合代码提交前跑/check命令里包含类型检查、测试、lint 三条执行指令然后跑/changelog生成变更说明最后跑/review做正式审查。这三个命令串起来就是一条可执行的团队 DevOps 意识流。工作流的另一个价值在于降低协作门槛。新成员加入项目不用啃几十页规范文档只要学会/check、/review、/commit这几个命令AI 就会按团队规范引导他完成任务。规范不再是纸面文档而是嵌入了工具的操作流程。6.2 重构类模板的工作流示例重构模板我一般这样写你是专注于代码重构的工程师。请按以下步骤处理重构需求 1. 分析目标文件的职责和依赖关系绘制改动影响面。 2. 列出当前代码的问题清单包括重复逻辑、过长函数、隐式依赖。 3. 给出重构方案优先采用小而可靠的步骤避免一次性大改动。 4. 每完成一步重构运行一次测试确保无回归。 5. 重构完成后输出前后对比说明。 目标文件$1这个模板强制模型先把问题列清楚再动手改代码能有效避免“模型直接重写一通结果项目挂了”的惨案。重构类任务最大的风险是改动面失控模板加入“影响面分析”和“每步测试”的步骤约束正好对症。6.3 测试模板要注意的边界测试生成的模板关键不是让模型“写越多越好”而是引导它识别什么值得测。一个只能覆盖快乐路径的测试套件没有价值。我会在测试模板里加入一个“先分析后编码”的阶段1. 先阅读源文件列出所有可测试的行为点。 2. 区分核心逻辑和边界逻辑优先为核心逻辑写测试。 3. 对数据库、网络请求等外部依赖使用替身。 4. 运行测试失败用例需要分析原因不得直接删除断言。写测试的边界还包括“不要修改被测代码来适配测试”。模型经常为了测试容易通过顺手把业务逻辑改了这是很危险的。模板里必须明确禁止否则测试结果再好看也没有意义。6.4 文档模板让产出更规范团队项目里最让人头疼的是文档风格不统一。文档模板可以设定结构和语气。比如 README 模板要求包含项目简介、环境要求、快速开始、目录结构、常见问题。函数注释模板则要求包含功能描述、参数说明、返回值说明、异常说明。把这些写进模板文档产出就像流水线产品一样整齐。7. 模板不生效一份实战排查清单模板写好了却不生效是大家遇到最多的问题。我整理了一份排查清单按出现频率排序基本上能覆盖八成的故障。7.1 路径放错是最常见的原因斜杠命令没出现在命令列表里先确认文件是否放在.claude/commands/以及文件名是否符合命名规范。CLAUDE.md 没生效检查一下是不是放在了用户主目录而不是项目目录或者文件名大小写是否写错。路径问题通常不会报错只会“静默失效”所以每次新增文件后都要主动验证一下。7.2 修改模板后忘了重新加载Claude Code 在会话启动时加载配置运行中新增或修改的模板不一定立即生效。我习惯在改完模板后直接重启会话或者输入/memory或类似命令触发重新加载。如果你发现改了半天内容没作用先别怀疑语法重启一下往往会解决问题。7.3 上下文被撑爆的典型表现模板写得越多上下文占用越多。如果模型回答开始变慢、在长对话中包含重复内容、或者明显忽略你模板里的指令大概率是上下文过载了。处理办法很简单精简模板把不常用的大段内容移到斜杠命令或 Skills 里按需加载而不是全部常驻。7.4 版本更新导致字段不再兼容Claude Code 迭代速度挺快不同版本的 frontmatter 字段、命令参数写法可能有差异。如果你在社区抄了一堆模板回来发现部分命令报错或不被识别先检查工具的版本说明确认字段名是否仍然适用。模板发行时最好标注适用的工具版本免得误导使用者。7.5 模板共享的卫生习惯模板里很容易混入敏感信息比如内部 API 地址、密钥占位符、个人工作路径。在公开分享模板仓库前建议全局搜一遍代码中是否包含.env、密钥、真实域名、内部接口路径。另外也不要把个人喜好的操作风格强塞进团队共享模板授权给整个团队的模板应该以团队约定为准而不是某一个人的习惯。8. 最后我自己的习惯用模板梳理 Claude Code 的工作方式我最大的体会是“模板其实是给自己用的”。它不只是约束模型更是一次次在整理自己到底希望 AI 怎么工作。写着写着你会发现自己最看重的不是 AI 写代码多快而是它能不能在你最在意的边界上不犯错。我自己现在的做法是所有项目共用的规范放在用户目录技术栈相关约定放在项目根目录的 CLAUDE.md而代码审查、测试、文档这类高频动作用斜杠命令固化偶尔遇到深度任务再临时写一个子代理。这套组合让我每次开新项目时不用花一上午重新给 AI 讲规矩而是几分钟内让它进入状态。如果你刚开始整理自己的模板别追求一步到位。先从一个 review 命令、一段 CLAUDE.md 的约束部分开始跑几周再迭代。模板不完美没关系关键是它能让你和 AI 之间的配合越来越顺手这才是 claude-code-templates 最值得花时间的理由。
