如果只用一句话总结我在实际工程里折腾claude-code-templates的感受那就是模板不是写给 AI 看的是写给未来那个又要重复解释一遍背景的自己看的。我最早用 Claude Code 的时候每个新会话都要花五六分钟重新交代技术栈、目录结构、编码规范说的内容一模一样AI 该犯的错一个没少。后来我把项目里沉淀出的提示词、CLAUDE.md、斜杠命令、甚至整个新仓库的初始化流程全部模板化成体系地放进.claude/目录才真正体会到什么叫一次配置长期收益。这篇东西适合谁适合那些已经用上 Claude Code、但总觉得它不够懂你项目的人也适合准备在团队里推广 AI 辅助开发的工程负责人。我会从 CLAUDE.md 的写法讲起然后拆自定义斜杠命令、提示词模板的设计方法、整套脚手架模板怎么搭最后把我踩过的坑一起说出来。整个过程里只讲我实际验证过的东西你拿过去就能改着用。1. CLAUDE.md 模板给 AI 一份入职手册而不是产品简介1.1 为什么很多人的 CLAUDE.md 写了跟没写一样我见过太多团队直接把 README 换个名字就当成 CLAUDE.md 用。里面写着本项目是一个基于 Vue 3 TypeScript 的后台管理系统使用 Pinia 管理状态Element Plus 作为 UI 库…… 这没错但基本没用。因为 AI 读完这种简介只知道项目里有什么依然不知道该怎么干活。真正的 CLAUDE.md 要回答的是下面这类问题改一个接口时是先改类型定义还是先改 mock 数据提交代码时commit message 应该用什么前缀写测试的时候是优先补单测还是补集成测试某个目录是不是禁止手工修改、只能由代码生成器产出这些问题 TECHNICAL 背景完全不同但有一个共同点它们在每次会话里都会被反复问到。你不写清楚AI 就会用它的通用常识来猜猜出来的东西可能在语法上完全正确但放在你的项目里就是不合规矩。我自己有一个很直观的对比某个支付模块的老仓库没写 CLAUDE.md 时AI 生成的新增接口总是忘了在事务里处理回调代码能跑但资金对不上账。后来我把涉及支付流程的修改必须使用Transactional必须在 try/catch 里显式处理退款失败写进 CLAUDE.md同样需求再让 AI 做一次就对了。所以 CLAUDE.md 的第一原则是把你希望 AI 怎么做决策写成规则而不是把项目有什么写成介绍。内容定位错了写多长都白搭。1.2 一个可复用的 CLAUDE.md 骨架我现在的新项目都用一个固定的 CLAUDE.md 骨架大概 60 到 120 行按优先级分成几个区块。写给你看一下结构你可以直接抄回去改成自己的。# 项目基本信息 一句话说明项目业务目标这个系统解决什么问题核心用户是谁。 当前主要技术栈与关键版本框架、语言、包管理器。 本地开发常用命令安装依赖、启动、跑测试、构建、代码检查。 # 目录结构与修改禁区 - src/ 下各目录职责一句话说明 - 禁止手工修改目录src/generated/ 内容由 npm run gen 生成 - 涉及跨模块改动时必须同步更新 src/types/api.ts 中的类型定义 # 编码规范与做事标准 - 新代码遵循项目的 ESLint Prettier 配置提交前跑一遍 - 后端接口统一返回 { code, data, message } 结构 - 新增异步操作必须考虑错误处理不允许裸 promise - 单元测试用 Vitest 写文件名后缀统一 .test.ts # 高频业务规则 - 订单模块状态流转只能按 待支付 - 已支付 - 已发货 的路径进行 - 用户模块删除用户是软删除字段 deleted_at 置位 - 权限模块新增接口必须在权限表中登记权限点 ID # 常用命令与脚本 - npm run dev本地开发默认端口 5173 - npm run generate:model根据数据库表结构生成模型文件 - npm run check先跑类型检查再跑 lint合入前必须通过这个骨架的关键在于每条规则都写得像一个可执行命令而不是一个模糊建议。比如说注意代码质量就没用但提交前跑npm run check失败不能提交就是 AI 能直接执行的指令。框架类的规则给一两条最核心的就够最忌贪多。我还喜欢在 CLAUDE.md 里放角色定位一小段。比如你是一个精通该支付系统的资深后端工程师当需求描述模糊时先列出你理解到的三种可能再选最合理的一种继续不要直接动手。这会让 AI 在最容易跑偏的地方停下来问一句省掉后面大段返工。其实这就是在给 AI 设定一个高年资同事的人设很多上下文问题它会自己补上。1.3 全局配置与项目配置的分工CLAUDE.md 可以放在两个层级一个是用户级通常在~/.claude/CLAUDE.md一个是项目级仓库根目录的./CLAUDE.md两个文件会合并加载项目的配置会覆盖或补充全局配置。这个机制特别适合分离个人喜好和团队事实。我在全局配置里放的是和工作风格相关的东西比如commit message 统一用 Conventional Commits 格式代码注释用中文还是英文我习惯中文注释但团队要求英文就按项目来通用代码风格偏好比如函数超过 80 行就该考虑拆分不希望 AI 默认调用的工具列表比如禁止在没有 README 的情况下直接猜 npm scripts在项目配置里则放只对该仓库成立的硬性事实比如上面 1.2 里的目录结构、业务规则、部署流程。这样我切到任何一个项目全局偏好会在而每个项目的细节各自维护互不污染。一个小技巧如果你在团队里推这套东西全局 CLAUDE.md 不要强制统一因为每个人的工作习惯不同。但项目级 CLAUDE.md 一定要让全员共用同一份而且写清楚改这里要过 review。它就是团队的 AI 协作规范和.eslintrc是一个级别的文件。2. 斜杠命令模板把重复劳动变成一个 /review2.1 没有命令模板之前的痛苦CLAUDE.md 解决的是AI 懂不懂项目的问题但还有一个更日常的痛每次让 AI 做同一件事都要打一长串提示词。比如做一次代码审查我以前会输入请对我本次改动的这几个文件做代码审查重点看有没有内存泄漏、有没有并发问题、错误处理是否完善输出按严重程度排序并给出修改建议。复制粘贴次数一多就烦了而且每次打的字还有细微差别AI 的输出格式也跟着飘。后来我把这类高频动作做成了斜杠命令/review。在对话框里输入这一条AI 就会执行我预先写好的完整逻辑输入输出都稳定。实际上Claude Code 的自定义命令机制就是在项目目录下放一个.claude/commands/文件夹里面每个.md文件就是一条斜杠命令文件名就是命令名。把一段重复提示词存成文件这个思路不难但它带来的确定性收益非常大。2.2 命令文件怎么放、怎么写先看一个我项目里真实在用的review.md命令模板--- description: 对暂存区代码进行系统性审查 --- 你是一名高级代码审查员。请按以下步骤执行 1. 执行 git diff --cached --stat 查看本次变更概览 2. 执行 git diff --cached --name-only 获取文件列表找出新增或修改的源文件 3. 逐个阅读这些文件的关键改动重点检查 - 并发场景下是否存在竞态条件 - 资源使用后是否正常释放连接、文件句柄、定时器等 - 有没有直接把异常吞掉的 catch 块 - 新增公共接口是否缺少边界校验 4. 按「严重 / 中等 / 建议」三个级别输出问题清单 5. 每个问题必须给出具体文件路径和行号并给出修改示例 本次需要额外关注的业务约束$ARGUMENTS这个文件里的$ARGUMENTS是魔法变量用户输入/review 重点看登录模块的 token 刷新逻辑时后面那段话会自动替换到$ARGUMENTS的位置。这样命令模板本身是通用的但每次审查关注点可以临时指定不用改文件。命令文件的组织方式上我建议按场景分目录。比如.claude/commands/ ├── review.md ├── test-generate.md ├── changelog.md ├── pr/ │ ├── create.md │ └── update-description.md └── legacy/ ├── explain.md └── migrate.md这样命令会自动变成/review、/pr/create、/legacy/explain语义清晰也不容易重名。目录层级不要太深两层基本到顶再深就很难记了。有一点要注意命令文件默认执行前会让用户确认。如果你确认自己的命令模板足够安全比如只是读取文件或者生成文本可以在命令前加!变成review!这种无确认执行。我一般只在很可信的只读命令上这么干凡是会改文件、跑脚本的都留着确认不然 AI 自作主张改了状态后果很麻烦。2.3 命令模板如何复用和组合命令模板最好的用法不是堆数量而是能组合。我现在的.claude/commands/目录里大概有二十来个命令但日常翻来覆去用的核心命令不超过十个。真正让我觉得值得的是几个命令连起来能覆盖一条完整工作流。拿发一个 Pull Request 举例。我之前要先后让 AI 做几件事跑测试、审查代码、生成变更描述。现在我把它们串成了/pr/prepare一条命令--- description: 提交前全套检查生成 PR 描述 --- 按以下顺序执行任务 1. 运行 npm run check如果有失败停下来报告失败内容不要继续 2. 运行 npx vitest run统计失败用例数 3. 对比 git diff --stat确认变更范围 4. 基于以上步骤执行代码审查流程检查是否存在明显问题 5. 生成 PR 描述包含变更背景、主要改动点、测试情况、需要 reviewer 重点关注的区域 命令行格式pr 描述这样一条命令把原本四步的机械操作压缩成一次会话。而且因为步骤一失败就停不会出现带着错误继续跑的滑稽场面。组合命令还有一个隐藏好处命令本身变成了团队的流程文档。新同事想了解提交代码前到底要做哪些检查不用翻文档看一眼.claude/commands/pr/prepare.md就全明白了。这比 wiki 里躺着的流程说明不知道高到哪里去了。3. 提示词模板设计命令式、上下文、输出锚点3.1 模板写不好会怎么死CLAUDE.md 和斜杠命令本质都是提示词模板但写提示词模板有很多容易被忽视的失败模式。我总结了三种最常见的死法第一种死法太宽泛。比如请审查代码五个字AI 完全自由发挥输出质量全看运气。它可能只看了表面风格问题真正的并发隐患一个没提。这不是 AI 不行是你没给它聚焦的指令。第二种死法太啰嗦。一个命令里塞了七八个目标还有大段背景故事AI 读的时候前面指令被稀释执行时经常漏掉后面的关键要求。上下文窗口是有限的模板里的每个字都在占用 AI 的注意力废话越多关键指令越容易被忽略。第三种死法没有输出锚点。你让 AI分析一下这段代码它回你一段情感充沛却没有结构的散文。你说得清楚还好说不清楚就还得反问一轮。模板里如果没定义输出格式AI 就会拿它在训练数据里最常见的格式来应付你。所以我后来设计模板时给自己定了一条规矩每条模板至少解答三个问题——做什么在什么条件下做产出物长什么样3.2 三段式模板设计法按这个思路我用的模板结构固定成三段命令式开头动词开头的一句话直接说清要做什么。审查生成重构解释都行绝不用请帮我看看能不能……这种带商量语气的写法。指令越干脆AI 越不会犹豫。上下文与约束包括输入来源哪个文件、哪段 diff、必须遵守的规则、禁止事项、如果条件不满足时的处理方式。这部分的每个句子都要能被执行不要出现注意安全保证质量这种不可操作的空话。输出锚点明确要求输出什么格式、分几个章节、需不需要给代码示例。最好连如果没有发现问题就明确说未发现严重问题这种兜底话也写进去不然 AI 为了表现自己总会凑几条建议。用一个通用公式表示就是[做什么] [输入/范围] [约束条件] [输出结构] [兜底行为]这五要素不一定每次全用但动笔之前过一遍这个公式能逼自己想清楚。我自己写模板时有个有趣的习惯先写输出锚点再倒推前面的指令和约束。因为输出结构是模板的心脏它定了前面要喂什么信息自然就清楚了。3.3 三个可以直接抄的模板案例我直接在项目里用的三个模板给你看看都是踩过坑之后改出来的版本。案例一单元测试生成模板为以下文件生成单元测试 文件路径$1 要求 1. 仅测试该模块导出的公共函数不测试私有函数 2. 覆盖正常路径、边界值、异常输入三组场景 3. 测试文件放在 tests/unit/ 下文件名以 .test.ts 结尾 4. 使用项目已有的测试框架和风格禁止引入新依赖 5. 输出每个测试用例的命名和对应场景列表再给出完整代码这里$1是位置参数用户在/test-gen src/utils/format.ts时自动生效。很多模板失败都是因为让 AI分析需求这个模板则直接给出了完整的方法论与路径。案例二旧代码逻辑梳理模板解释以下模块的实现逻辑与调用关系 文件$ARGUMENTS 输出格式 1. 模块职责一句话概括 2. 核心函数逐个说明输入、输出、副作用 3. 被其他模块引用的位置列表用 grep 结果 4. 该模块中你认为可以重构的点按优先级排序这个模板看起来简单但它的价值在于第四条。单纯让 AI解释代码它只会复述明确要求给出可重构点排序后它才会带着审阅视角去读代码输出立刻就不一样了。案例三变更日志生成模板根据 git log 生成最近一次发布的变更日志 范围git log $(git describe --tags --abbrev0)..HEAD 要求 1. 按 feat / fix / refactor / docs / test 分类 2. 每条描述不超过 20 个字使用祈使句 3. 将 commit hash 附在每条后面格式为 (abc1234) 4. 输出标题 ## Changelog下面是分类列表这类模板有个共同点输出锚点都非常具体。AI 生成完你几乎不用改格式直接贴进 release note 就能用。4. 项目脚手架模板新项目开局直接复制整套 AI 工作流4.1 脚手架模板不只是一堆目录如果说前面都在讲怎么用模板让 AI 更懂当前项目那这一步就是怎么把整套模板体系复制到新项目里。我每次开新仓库目录结构里必带一套.claude/配置内容包括CLAUDE.md基本信息、编码规范、目录结构commands/团队通用的命令模板比如 code-review、test-generate、changelogagents/按场景拆分的子代理定义文件settings.json权限配置配合 hooks 使用这听起来只是复制几个文件但效果差别很大。以前我开新项目AI 是从零开始认识项目的头两天对话质量低到令人发指。现在开局就带CLAUDE.md和一套命令AI 的表现直接跳到入职半年的水平省掉的不只是时间还有前期的挫败感。4.2 用脚手架模板统一团队工作流团队里推广模板最大的难题不是写而是分发和同步。我见过有人把模板往共享盘一扔半年后项目里跑的还是初版模板问题越攒越多。所以我把整套模板放在独立仓库里维护和业务代码分开理由很简单模板升级不影响业务仓库团队里谁觉得命令不好用可以直接提 PR 改模板仓库新项目初始化时从模板仓库拉一份下来即可一个比较实用的同步方式是模板仓库里写一个初始化脚本把模板目录复制到当前项目#!/usr/bin/env bash # init-claude-template.sh TEMPLATE_REPO_URLgitexample.com:team/claude-templates.git TEMPLATE_DIR.claude if [ -d $TEMPLATE_DIR ]; then echo 已存在 .claude 目录跳过复制 exit 1 fi git clone --depth 1 $TEMPLATE_REPO_URL /tmp/claude-templates cp -r /tmp/claude-templates/template $TEMPLATE_DIR rm -rf /tmp/claude-templates echo 初始化完成记得按项目情况检查 CLAUDE.md 中的个性化配置脚本做得糙一点没关系关键是别手动一个个文件拷贝。手动拷贝最大的问题是顺手改了几个文件下次同步时冲突一堆最后谁也不知道哪个版本是权威的。模板仓库 一份初始化脚本能省掉大量维护成本。项目级模板放到业务仓库之后像 CLAUDE.md 这种文件还得随着项目变化持续更新。我用的检查办法有点笨但很好用经常留意 AI 在对话里反复问哪些问题只要一个类型的问题出现三次以上就是该把它写进 CLAUDE.md 的信号。4.3 模板、子代理与 hooks更进一步的自动化当模板数量多起来之后我发现单纯靠一个 AI 在主对话里完成所有任务开始力不从心。比如既要写代码又要 review 代码还要做架构分析一个上下文窗口里塞得太多效果会互相干扰。这时候就需要拆子代理subagents。子代理的核心思路是把特定的指令模板封装成一个独立代理在需要时才加载。它和普通命令模板的区别在于命令模板是在当前对话里套用指令子代理则有独立的上下文空间可以在主对话之外做专门审查。举一个项目里的例子我定义了一个reviewer子代理只负责代码审查不在乎生成新代码。这样主对话里的 AI 专注写业务专门的质量检查交给专门的代理互不抢占上下文产出质量比我早期把所有任务压在一个对话里要高不少。settings.json里的 hooks 则是另一层自动化。我目前用得最保守也最实用的是跑测试的 hook每次往暂存区提交前自动触发测试命令失败的话把结果贴回对话让 AI 自己看到错在哪。这个不吃性能但对反馈闭环很有帮助。不过自动化这块我强烈建议宁少勿多。hooks 一旦加上每次对话触发都会消耗 token还得承担误触发风险。开局阶段先把 CLAUDE.md 和命令模板用好再看有没有必要引入 hooks。5. 我踩过的坑模板设计里最容易出问题的几个位置5.1 CLAUDE.md 越长效果越差模板刚建起来的时候我一度很贪婪什么规则都想往里写项目级 CLAUDE.md 写到了将近 200 行。结果 AI 的表现不升反降经常出现前面说要 A后面说不要 A的指令冲突AI 自己都懵了。后来我把 CLAUDE.md 当成代码质量重要文档来管理给自己定了一个非常硬性的标准项目级 CLAUDE.md 超过 150 行就必须做减法。核心业务规则保留那些一次性的、推导出来的细节全部从主文件里删掉转移到相关模块的说明文档中。如果确实有大量需要 AI 知道的上下文就把信息拆到子代理专属的提示词里需要时才加载而不是一股脑塞进主文件。5.2 命令模板过度参数化命令模板刚支持位置参数的时候我像拿到新玩具一样一个命令恨不得塞五个参数进去$1、$2、$3全用上。结果预期中的灵活性没换来倒是命令本身越来越难用。每次执行命令前都得想一遍第一个参数是什么来着还不如直接手动输入提示词。这是我的切身体会命令模板的参数撑死两个能不用就不用。大多数情况下$ARGUMENTS一个捕获全部输入就够位置参数只用在真正需要多段落分开解析的场景。模板的灵活性是设计出来的不是参数越多越灵活参数一多使用者就被迫去记模板的接口签名这和我们写代码时讨厌长参数列表是一个道理。5.3 把模板当成一次性摆设还有一类坑是模板建好之后没人维护。我的判断标准是一个模板如果已经连续三个版本没被改过很可能它已经默默报废了。我会观察它实际还在不在用对话里有没有人继承这个命令反馈出来的效果对不对。拿review.md来举例我最初版本里没写检查竞争条件因为当时项目是单线程的。后来项目接了一个消息队列并发问题变成高危项我第一次用 review 命令时发现了这个缺口马上把它补进去。模板必须跟着项目一起演进它不是建完就死的文档而是活的工具链。5.4 最终一个小技巧从 AI 的问题反推模板缺陷最后分享一个我到现在还在用的习惯。每次跟 Claude Code 对话如果 AI 在我说完需求之后问了一句你的项目是什么技术栈或者这个目录代表什么之类的问题我不会只回答它。我会立刻记录为什么它不知道是不是 CLAUDE.md 里没写是不是写了但太隐蔽只要问题重复出现两次以上我就把答案补进对应文档。坚持一两个月CLAUDE.md 和命令模板会变得越来越精准。我会把 AI 反复问的问题当作一种测试反馈反推模板哪里有缺口。这套闭环维护的思路远比一次写一个完美模板更实际因为完美的模板根本不存在但持续演进、持续贴近项目现实的模板就是生产力本身。
