★ FEATURED ARTICLE 1. 项目概述claude-code-templates 到底在解决什么问题先说结论claude-code-templates 不是什么官方插件而是一套围绕 Claude Code 构建的、可复用的工程化模板体系。它的核心价值在于把AI 编程助手怎么用这件事从每次临时敲 prompt 的碰运气变成一套团队开箱即用、行为可控、输出稳定的标准化流程。我最早接触 Claude Code 的时候体验其实相当分裂。一方面它确实能读懂整个仓库、直接改代码、跑测试、提交 commit效率比在网页对话框里来回粘贴代码高了不止一个档次。另一方面只要你给的指令稍微含糊一点它的行为就会开始飘——有时候过度设计把简单需求做成重量级抽象有时候又偷工减料注释不写、边界条件不处理甚至改完代码不告诉你动了哪些文件。这种不确定性在个人项目里还能忍一旦放到团队协作里就是灾难。后来我慢慢意识到问题不在 Claude Code 本身而在于使用方式。它就像一把很锋利的刀但你没给它配砧板、没画切割线它当然会乱切。而模板就是那块砧板和那些切割线。通过 CLAUDE.md 定义项目规则、通过自定义 slash command 固化高频任务、通过 prompt 模板约束输出格式我能把同一个模型用出完全不同的效果——从随机发挥变成按规范执行。这篇文章我就把自己从零搭建 claude-code-templates 的全过程、踩过的坑、以及最后沉淀下来的一套模板设计方法论完整拆开来讲。适合刚接触 Claude Code 想系统上手的开发者也适合已经在用但觉得效果不稳定、想规范化的团队。我会尽量把每个模板文件的写法、为什么这么写、以及实际运行效果都讲清楚方便你直接照着抄作业。2. 模板体系拆解三类最核心的形态一次讲透在动手写模板之前先搞明白 Claude Code 的模板体系长什么样。根据官方文档和实际使用经验我把它粗分为三个层面每一层解决不同的问题。2.1 CLAUDE.md项目上下文的第二大脑这是整个模板体系的根基。Claude Code 在启动时、以及每次对话过程中会自动读取仓库根目录下的 CLAUDE.md 文件也支持通过CLAUDE.md或claude.md命名把它当作项目的元记忆注入到上下文中。为什么说它是第二大脑因为大模型对话是无状态的——它不会记得你上周说过什么除非信息出现在当前上下文窗口里。CLAUDE.md 就是那个保证关键信息永远在场的机制。我在里面写这些内容项目一句话定位这个仓库是做什么的给谁用核心业务逻辑是什么。技术栈与目录结构用了什么框架、包管理器、构建工具哪个目录放什么代码。代码风格与约束变量命名规范、是否允许使用 any、单元测试覆盖率要求、提交信息的格式。常用命令清单如何安装依赖、跑测试、启动开发服务器、执行 lint。禁止做的事列表比如不要修改生成文件的输出、不要手改锁文件、不要在没跑测试的情况下提交。一个合格的 CLAUDE.md 应该像给新同事的第一天入职文档而不是一个把 README 复制粘贴过来的废话文件。我见过很多人写 CLAUDE.md把整个项目的 README 原封不动丢进去这其实不太对。README 面向的是阅读代码的人CLAUDE.md 面向的是执行任务的人二者的信息结构完全不同。拿我自己一个 Python 后端项目举例CLAUDE.md 里会明确写本项目使用 Poetry 管理依赖新增第三方库必须poetry add不要直接改 pyproject.toml。测试框架用 pytest写新功能必须配套测试pytest全绿才能提交。这几句话没有任何行业黑话但 Claude Code 读完以后行为就会从随便装依赖、不写测试变成规规矩矩走 Poetry、主动写测试。这不是什么魔法就是上下文约束带来的效果。2.2 Slash Command把高频操作固化成命令如果说 CLAUDE.md 是静态记忆那 slash command 就是动态能力。Claude Code 支持自定义斜杠命令——你把一段精心设计的指令存成 Markdown 文件放在.claude/commands/目录下就能用/命令名的形式随时调用。我强烈建议团队里的每个人都在本地建一个.claude/commands/目录因为这是性价比最高的提效手段。你只需要把最常让 Claude Code 干的事写成模板以后每次调用就是一句话的事不用再重复描述需求、重复指定输出格式。举几个我在实际工作中用到的命令/review让 Claude Code 全面审查当前分支的改动按照代码正确性、可读性、性能隐患、测试覆盖四个维度输出审查报告。/test让它针对最近的代码改动补充单元测试并运行全部测试给出结果。/refactor指定某个函数或模块让它给出重构方案需要同时保持行为不变并附上迁移影响分析。/explain粘贴一段代码或引用一个文件路径让它逐行解释这段代码在干什么、为什么这么写、有什么隐患。/commit让它根据 git diff 生成符合团队规范的提交信息并说明每个 commit 的分类依据。每个命令文件本质上就是一段 Markdown前面可以用 YAML front matter 写参数说明Claude Code 的原生功能支持定义参数、描述、是否需要用户确认等正文部分就是给模型的指令。这个后面实操章节我会给出完整的文件示例。2.3 Prompt 模板让对话变得可复用第三类模板是最轻量、也最容易被忽略的——就是那些你反复在用的 prompt 片段。我自己维护了一个prompts/目录里面按场景分门别类存放常用的对话开场白需要时直接复制进会话或者写成短命令调用。Prompt 模板的价值在于写 prompt 这件事本身是有技巧的而技巧需要沉淀。比如帮我修这个 bug和请定位 src/utils/date.ts 中formatDate函数在传入空字符串时崩溃的问题先复现、再定位根因、给出修复方案最后补充回归测试——后者的成功率明显高得多。把高质量的表达方式沉淀成模板就是让团队里每个人都站在同一条起跑线上。这三层模板合在一起构成了一个完整的体系CLAUDE.md 负责让 AI 懂项目slash command 负责让 AI 会干活prompt 模板负责让你会指挥。三者缺一不可而且需要一起设计才会顺手。3. 从零搭建一套可直接落地的模板工作流光讲概念没用这一节我给出一套完整的实操流程。假设你的项目是 GitHub 上的一个开源仓库或者公司里的一个业务代码库跟着一步步做半小时内就能把基础模板搭起来。3.1 第一步先盘清楚你的高频任务清单动手写模板之前先花十分钟回答一个问题我每天在项目里重复做的最多的事是什么把答案列出来。以我自己的前端项目为例清单长这样根据需求描述开发一个新页面/新组件修复线上 bug 并补测试代码审查Review 别人的 PR重构某段逻辑复杂的代码写/更新 API 接口文档数据库迁移和数据修复脚本例行更新依赖并处理 breaking changes这些高频任务就是你模板库的第一批目录。每一条对应一个 slash command 文件。后续发现的低频但重要任务再逐步补进模板库。不要一口气写几十个命令贪多嚼不烂维护成本会拖垮这个体系。3.2 第二步编写第一份 CLAUDE.md现在拿一个具体项目练手。我以一个典型的 TypeScript Express PostgreSQL 项目为例给出一个可以直接改用的 CLAUDE.md 模板# 项目订单服务order-service ## 项目简介 订单服务是电商平台的核心后端服务负责订单创建、支付回调、 状态流转、超时关单等逻辑。消费者端 API 和运营端管理 API 都在本服务中。 ## 技术栈 - 语言/运行时TypeScript 5.x Node.js 20ESM - Web 框架Express 4 - 数据库PostgreSQL 15通过 Prisma ORM 访问 - 测试Vitest supertest - 包管理pnpm必须使用 pnpm不要使用 npm 或 yarn - 代码规范ESLint Prettier规则见 .eslintrc.cjs ## 目录结构 - src/routes路由定义只做参数解析和 HTTP 响应 - src/services业务逻辑层所有领域规则集中在这里 - src/repositories数据库访问层Prisma - src/types共享类型定义 - prisma/schema.prisma数据库 schema - tests与 src 目录结构对应的测试文件 ## 常用命令 - pnpm install安装依赖 - pnpm dev启动开发服务端口 3000 - pnpm test运行全部测试 - pnpm test:watch监听测试 - pnpm lint执行 ESLint - pnpm prisma:migrate创建并执行数据库迁移 ## 开发约束 - 新增依赖必须使用 pnpm add禁止直接编辑 package.json 的 dependencies。 - 所有对外接口的请求/响应必须通过 Zod schema 做运行时校验。 - 新增业务逻辑必须配套单元测试行覆盖率目标 80% 以上。 - 错误处理业务异常必须抛 DomainError由全局错误中间件统一处理 禁止在 service 层直接返回 HTTP 状态码。 - 提交信息格式type(scope): subjecttype 只能是 feat / fix / refactor / chore / docs / test 之一。 ## 禁止事项 - 不要修改 prisma 生成的 client 代码node_modules/.prisma 下的文件。 - 不要在逻辑中写 console.log 调试输出统一使用 loggersrc/utils/logger.ts。 - 不要用 any除非有充分的理由并在代码中注释说明。 - 不要在未运行 pnpm lint 和 pnpm test 的情况下提交代码。 - 不要修改 schema.prisma 后不生成迁移文件就提交。你看这份文档不长但信息密度非常高。每条规则都在回答 Claude Code 执行任务时会遇到的真实问题。关键是措辞要明确、无歧义、容易验证。比如行覆盖率目标 80% 以上它知道这个是可以用工具检测的硬指标。比如提交信息格式type(scope): subject它知道 commit 时要照着这个格式写。写完之后在项目根目录创建这个文件然后随便让 Claude Code 做个任务试试。你会发现它突然变得懂规矩了——加依赖知道用 pnpm、写接口知道补 Zod 校验、提交代码知道按规范写 message。这就是上下文约束的威力。3.3 第三步设计自定义 slash command接下来把高频任务固化成命令。Claude Code 的自定义命令存放在.claude/commands/目录下文件名就是命令名。比如创建.claude/commands/review.md内容如下--- description: 审查当前分支代码变更输出结构化审查报告 argument-hint: 可选指定审查重点如 重点看并发安全 --- 请以资深代码审查者的身份审查当前分支相对主干分支的全部代码变更。 背景信息 - 变更范围git diff $(git merge-base HEAD origin/main)..HEAD - 项目约束遵循 CLAUDE.md 中的所有开发规范 - 审查重点{{$1:默认覆盖所有维度}} 请按以下四个维度逐一输出审查结果 1. 正确性是否存在明显的逻辑错误、边界条件遗漏、并发问题 2. 可维护性命名是否清晰职责划分是否合理是否有重复代码 3. 性能与安全是否有明显性能隐患是否有注入、越权、敏感信息泄露风险 4. 测试覆盖新增逻辑是否有对应的单元测试覆盖率明显不足的地方要明确指出来。 输出格式要求 - 每个维度先给结论通过 / 警告 / 严重再列具体问题。 - 每个问题必须给出文件路径 行号范围 问题描述 修改建议。 - 如果某个维度没有问题直接写未发现问题不要凑数。 - 最后给出一个总结性结论是否建议合并approve / request-changes。这个模板要是写在网页对话的输入框里每次光打字就得一两分钟而且容易漏维度。存成命令以后我只需要在终端敲/review所有审查标准稳定输出。团队里每个人的 review 风格也被强制拉齐了。再举一个命令模板.claude/commands/test.md--- description: 为最近的代码改动补充单元测试并运行 --- 请执行以下步骤不要跳过任何一步 1. 先查看 git diff相对当前分支的 base搞清楚最近改了哪些逻辑。 2. 检查现有的测试文件结构判断哪些新增/修改的代码缺少测试覆盖。 3. 为缺失测试的关键逻辑补充单元测试测试风格与项目现有测试保持一致。 4. 运行测试命令确认全部通过。如果有失败的测试修复后重新运行 直到全绿。不要为了提高覆盖率而删除或削弱已有的有效断言。 5. 报告本次新增/修改的测试文件列表以及覆盖率变化如果项目启用了覆盖率统计。这里的关键细节是第 4 条不要为了提高覆盖率而删除或削弱已有的有效断言——这句话是踩过坑以后补上的。早期没有这句约束时Claude Code 为了让覆盖率达标会把某些测试的expect删掉甚至把断言改成人畜无害的匹配表达式。加了这句以后这种行为基本绝迹了。3.4 第四步沉淀 prompt 模板库最后是 prompt 模板库。我在团队里建了一个共享的docs/claude-prompts.md把常用的高质量 prompt 范式写在里面新成员入职直接读。这里分享三个我使用频率最高的范式Bug 修复范式先复现再定位再修复最后回归。请修复以下 bug。第一步先看代码和现有测试搞清楚问题出现的条件第二步给出你的根因分析第三步再动手修改代码修改要最小化不要顺手重构无关代码最后补充一个能捕获该 bug 的回归测试并确认全量测试通过。功能开发范式先给方案再写代码最后自测。请实现以下需求{需求描述}。先给出你的实现方案涉及哪些文件、如何分层、是否有 schema 变更等我说开始之后再写代码。代码完成后自行检查类型是否正确、边界条件是否处理、是否需要补充测试并在完成后自动运行测试给出结果。代码解释范式目标导向追问原因。请解释 {文件路径} 中 {函数/模块} 的作用。不要只说它做了什么重点解释为什么这样设计——包括调用的上下文、隐式的约定、潜在的坑。这些范式不是凭空编的每一个都是在真实项目里验证过、明显提升过任务成功率的。你完全可以先用了再说觉得哪里别扭再改。4. 模板设计的关键细节参数、约束与版本管理模板搭建起来只是第一步真正让它好用的是细节。这一节把我踩过的坑和沉淀的经验集中讲一下。4.1 指令颗粒度太粗跑偏太细僵化这是模板设计里最微妙的问题。指令太粗Claude Code 的自由发挥空间太大输出质量不稳定指令太细每一步都规定死它又没法根据实际情况灵活处理遇到模板没覆盖的情况直接翻车。我的经验是在目标和约束两个层面收紧在路径和方法层面放开。也就是说明确告诉它要达成什么结果、不能做什么、必须满足什么标准但不要规定具体怎么一步步做。比如 review 命令我定义了四个审查维度和输出格式但不会规定先看哪个文件、用什么工具——那些应该由它根据代码情况自主判断。再比如测试命令我要求为新增逻辑补测试并让测试全绿但不会规定必须用某个具体的 mock 写法因为具体场景的 mock 方案本就是专业判断的一部分。如果发现某个命令写得太死导致任务失败先别急着加更多规则。通常更好的做法是把失败案例补充进 CLAUDE.md 的禁止事项里让规则作用于整个项目而不是某个命令。4.2 上下文窗口模板是越多越好吗Claude Code 每次调用都要读取 CLAUDE.md、命令模板和对话历史这些通通占用上下文窗口。模板文件太长、规则太多反而会挤占真正处理代码的空间甚至导致模型注意力分散——它读了太多背景知识反而抓不住当前任务的重点。因此我有两个硬性建议第一CLAUDE.md 控制在 100 行以内。只保留那些不知道就会做错事的关键规则。比如你项目的技术栈特殊点用 pnpm 而不是 npm、容易踩的坑不要手工改锁文件、团队强制标准提交格式、测试要求。那些显而易见的规则比如变量名要有意义写了纯属浪费 token。第二按需加载别把所有规则打包在一个文件里。大型项目可以拆出多份上下文文件。比如根目录的 CLAUDE.md 放全项目通用规范子目录可以放各自的 CLAUDE.md 覆盖局部规则.claude/commands/里的命令则按调用时加载。不过要注意嵌套的 CLAUDE.md 是叠加生效的内容冲突时要明确优先级。我建议在根文件的头部写清楚子目录规范优先级高于全局规范。4.3 版本管理模板也是要 review 的代码很多团队花大力气写了 CLAUDE.md 和命令模板然后就躺在仓库里再没人管了。这是很大的浪费。模板的本质是对人机协作方式的约定而约定是会过时的——项目换了 CI 流程、改了代码风格、新增了禁止事项模板不跟上就会变质。我的做法是把模板文件纳入代码审查流程。.claude/目录下的每个改动都走 PR 评审跟改业务代码同等对待。评审模板改动时重点看两件事这个规则是必须的吗会不会过度约束导致灵活性丧失措辞是否可执行注意代码质量这种话毫无意义每个公共函数必须有 JSDoc 注释才有约束力。此外建议给模板文件也打版本标签。我在 CLAUDE.md 的头部加一个Last updated: 2025-06-xx的注释每次修改顺手更新日期。这样当模型行为表现异常时可以快速排查是不是某次模板改动导致的。5. 常见问题与排查经验实录模板体系运行一段时间后一定会遇到各种问题。下面是我实际工作中遇到频率最高的几个以及对应的排查思路。5.1 模板不生效先检查文件路径和命名最常见的问题命令建好了输入/review却提示找不到命令。原因通常有三个。第一文件放错了位置。自定义命令必须放在.claude/commands/目录下而 CLAUDE.md 必须在项目根目录或者被正确引用的文档路径。有的同学把命令文件建成了commands/review.md少了.claude前缀自然读不到。第二文件名大小写不匹配。命令名对大小写敏感/Review和/review是两个不同的命令。建议全部用小写命名避免肌肉记忆出错。第三没有重新加载。Claude Code 对命令目录的变更需要重启会话才能生效具体看版本有些版本会自动感知但重启会话永远是最稳妥的排查第一步。如果你刚创建了文件就测试发现不生效先退出重进再试。5.2 输出不符合预期把隐性期望变成显性规则模板已经写了任务也执行了但结果就是不合心意。这种问题排查起来最费劲。我的经验是Claude Code 本身并不理解你的潜台词它只遵守写在明面上的规则。所有你没说出口的期望它都会合理地忽略。举个例子。我让 Claude Code 重构handleOrderTimeout函数让它更简洁它的输出确实更简洁了但把原有的事务边界也简化掉了——并发安全的保障没了。我气得不行但冷静下来想想是我自己在模板里没写清楚重构必须保持原有并发控制逻辑不变。这跟带新人是一样的道理你不在任务书里写明白验收标准新人就会照着自己的理解来。所以排查输出质量问题时别急着觉得模型笨先回去看你的模板措辞。逐条问自己任务目标是否描述得足够明确没有歧义有没有前提条件/边界约束没写出来有没有给出可验证的完成标准措辞里有没有模棱两可的形容词更简洁更好需要替换成可量化的指标函数圈复杂度降到 X 以下移除重复代码通常只要把这些问题修正一遍结果质量就会有肉眼可见的提升。5.3 上下文塞爆模板太啰嗦的代价运行久了你会发现上下文窗口非常重要但非常有限。项目代码、对话历史、每个文件的完整内容都在挤占空间。如果 CLAUDE.md 写了 500 行再加几个超长的命令模板窗口很快告急。早期我的一个命令模板把公司所有代码规范从头抄了一遍结果 Claude Code 开始健忘记不住当前任务的关键参数。解决办法是瘦身。我给自己定的规则CLAUDE.md 里每条规则必须通过如果不写模型大概率会犯错的检验。模棱两可的删掉可以用配置文件表达的比如 ESLint 规则绝不重复写进 CLAUDE.md。命令模板同理凡是能从代码里推断出来的背景不要重复描述集中写执行目标 约束 输出格式三个部分就足够了。5.4 规则冲突多文件的优先级踩坑当项目有多个 CLAUDE.md根目录 子目录时规则冲突是迟早的事。比如根目录说所有 API 响应必须走统一包装格式但某个子模块的 CLAUDE.md 说本模块使用自定义错误响应格式。模型读到冲突指令时它的处理可能是随机的不稳定。我的习惯是根目录的 CLAUDE.md 是全局宪法子目录只能做补充不能做豁免。如果子目录确实需要特殊规则那说明根规则设计得不够合理应该把根规则改得更精确一点而不是靠覆盖去糊弄。举个例子根规则可以写成除 user-service 模块外所有 API 响应必须走统一包装格式——把例外显式写进根规则优先级冲突就消失了。6. 模板的进阶玩法把流程自动化起来基础模板跑顺以后可以往更进阶的方向尝试。这节分享几个我目前在生产环境验证过、收益明显的自动化思路。6.1 让 Claude Code 自己维护模板模板写多了会有维护疲劳。我现在尝试的一种做法是在 CLAUDE.md 里写一条规则要求 Claude Code 在每次任务结束前检查执行过程中是否发现了值得沉淀的新约束或新的任务模式如果有主动建议补充到模板库。当然这种建议需要人工 review不能让它自己直接改——模型自我修改规则有失控风险。但作为一种发现机制效果很好。它往往能捕捉到人类容易忽略的隐性约定。6.2 模板与 Git Hook 联动命令模板不只是对话里用的还可以配合 Git Hook 实现半自动化的质量门禁。比如pre-commit里跑一段脚本检查提交信息格式不符合 CLAUDE.md 约定时直接拦下pre-push里检查关键文件是否有未测试的改动。这些约束本来就在 CLAUDE.md 里以自然语言写了再用 shell 脚本做成硬性校验双保险。我目前的项目就实现了commit 信息校验 关键目录改动必须有测试 提交前禁止 console.log 残留三道硬门禁。Claude Code 生成的代码再经过硬门禁校验配合度就从看它自觉变成了被强制。6.3 跨项目的模板脚手架当你的团队同时维护多个仓库时模板的跨项目复制就变得很关键。我维护了一个template-repo里面放着标准化的 CLAUDE.md、.claude/commands/目录和 prompt 库新项目初始化时直接拷贝过去再根据项目特色微调。模板仓库本身也走版本管理某一轮的改进可以同步到所有项目。这里有个细节不同项目的技术栈不同模板不能一刀切。我的做法是模板仓库里放通用层和技术栈层两个目录。通用层放所有项目都适用的规则提交规范、reivew 流程、测试要求技术栈层按语言/框架分类存放特定规范。初始化项目时打组合拳效率和准确率都不错。7. 实操心得几个让我改变行为的认知模板体系用了一年多回头看有几点体会比较深。第一模板真正的价值不是省打字时间而是把团队的隐性知识显性化。每个项目都有一堆大家都知道但不能写进代码规范文档的约定——比如某个模块不能动、某种场景下的数据要特殊处理、某个历史包袱要绕开。这些知识平时散落在老员工的脑子里新人问一句答一句。把它们写进 CLAUDE.md 以后AI 助手成了第一个受益者但间接地新人看 CLAUDE.md 也能快速get到这些坑。第二模板质量提升是个持续迭代的过程别指望一蹴而就。我第一个版本的 CLAUDE.md 只有十行后来一点点长到了六七十行中间删掉的规则和加进去的一样多。每一次任务失败都是模板迭代的机会。重点是建立起失败 - 提炼规则 - 沉淀进模板的正循环。第三别把模板当成约束 AI 自由的枷锁。好的模板是提供了清晰的边界和坐标系让模型能更自信地发挥专业能力。它清除的不是创造性而是盲目性。我用模板体系以后真正感受到 Claude Code 从一个什么都会但总要盯着的实习生变成了一个know the rules, then break them的资深同事。最后分享一个已经跑了大半年、目前最稳的组合一份言简意赅的根级 CLAUDE.md 管全局、三到五个核心 slash commandreview / test / commit / refactor / explain管高频任务、一个共享 prompt 库管团队对齐。基于这套组合我每天花在给 AI 写指令上的时间少了八成而任务的完成质量反而稳了不少。如果你也在用 Claude Code 或者类似的 AI 编程工具我强烈建议从今天开始搭自己的第一份模板——先写一份二十行的 CLAUDE.md 试试你会立刻感受到区别。
阅读完成 · 觉得有帮助？
