1. 先搞清楚claude-code-templates 到底解决了什么问题最近在重构一个老项目时我干了一件之前一直懒得干的事把所有常用的 Claude Code 提示词、工作流、代码审查清单、任务脚本全部整理成了一个模板库。整理完之后最大的感受是——这一周省下的时间比我过去三个月零零散散写提示词花掉的时间还多。如果你用过 Claude Code 这类 AI 编程工具大概会有同感功能很强大但每次新建会话都要重新交代一遍项目背景、编码规范、任务边界有时候写了一大段话进去AI 还是理解偏了。不是模型不行是你没给它一个稳定的上下文框架。而 claude-code-templates 说白了就是把这套上下文框架固化成文件让 AI 每次开工前自动加载一套成熟的工作模板。它能解决几个非常现实的问题告别每次重复敲提示词。项目背景、技术栈、目录结构、代码风格这些信息写进模板后自动生效不用每次重述。让 AI 的输出更稳定。同一个任务不同时间、不同会话执行的思路能保持基本一致不会这次给你重构、下次给你重写。约束 AI 不越界。模板里写明不可修改的文件禁止执行的命令这类边界条款能大幅减少 AI 擅自改代码带来的麻烦。沉淀团队经验。新人接手项目时把这些模板文件一读马上就能理解团队约定和常见坑比翻文档高效得多。适合谁参考如果你是 Claude Code 的重度用户每天靠它写代码、改 bug、做代码审查那你肯定用得上。如果你刚开始接触这类工具但已经被每次都要重新解释背景折磨得不耐烦了这篇文章同样值得看完。下文全部基于我个人已经跑通的一套模板方案列出了文件结构、核心写法、真实效果可以直接照抄也可以根据自己项目调整。2. 模板库的核心设计思路分类、分层、给 AI 立规矩2.1 先想清楚你要沉淀哪些可复用资产我在整理模板之前先列了一个需求清单发现日常使用 Claude Code 时真正反复消耗精力的场景无非这几类项目级规则代码风格、提交规范、禁止事项任务级流程重构、加功能、修 bug、写测试、做 Code Review单次操作执行命令、批量替换、解释代码、提交信息生成专场景模板前端、后端、数据脚本等不同领域的切入点对应这些场景我将模板库分成四个层级层级落地文件作用范围加载方式全局规则~/.claude/CLAUDE.md所有项目、所有会话自动加载项目规则CLAUDE.md当前项目自动加载共享命令.claude/commands/*.md当前项目slash command 手动调用一次性脚本.claude/skills/*.md按需调用输入 prompt 时引用自动加载的是前两类它们会进入 Claude 的系统提示词构成最基础的上下文。后两类是按需拉取的避免一次加载太多内容导致 AI 分不清重点。这个分层的核心逻辑是静态规则自动生效动态命令按需调用。把所有规则一股脑丢进全局文件里AI 会消化不良——它对会话早期出现的内容权重最高如果开头塞进去 500 行无用信息真正重要的规范反而会被稀释。分层之后全局文件只保留永远正确的内容项目文件只管当前仓库的具体约定剩下的统统交给按需加载。2.2 关键设计为每个模板设置触发条件与退出条件这是我踩了无数坑之后总结出来的最重要的一条经验。早期我的模板就是一段话让 AI 做完任务就行结果它经常跑偏——加一个字段能把相邻的三个模块全部重构一遍写个单元测试能给整个项目装上十几个新的依赖。后来我在每个模板开头都加了两个字段当且仅当和除非。举个例子我的重构模板开头是这样写的## 重构任务 当且仅当用户明确提出重构/优化/改善某模块时本模板生效。 除非 - 用户没有指定具体模块或文件范围 - 重构会破坏现有测试 - 涉及跨模块的大范围改动 以上情况出现时必须先向用户确认范围再继续执行。就是这样一个简单的当且仅当 除非结构把 AI 的自作主张概率降了一半以上。本质上是给 AI 一个行为判定逻辑什么时候该动手什么时候该停下来问人。这比单纯写请小心重构、不要乱改这种模糊提示要有效得多因为程序化的判定条件更容易被模型理解和遵守。2.3 目录怎么摆加载顺序怎么定我的模板库采用了一个很直接的目录结构claude-code-templates/ ├── CLAUDE.md # 项目入口全局规范 ├── docs/ │ ├── 01-quickstart.md # 快速上手说明 │ ├── 02-architecture.md # 架构说明 │ └── 03-workflows.md # 工作流总览 ├── commands/ │ ├── review.md # Code Review 指令 │ ├── refactor.md # 重构指令 │ ├── test.md # 测试生成指令 │ ├── commit.md # 提交信息生成指令 │ └── debug.md # Debug 会话指令 ├── skills/ │ ├── frontend-vue.md # Vue 前端任务 │ ├── backend-python.md # Python 后端任务 │ ├── database-migration.md # 数据库迁移任务 │ └── api-design.md # API 设计任务 └── scripts/ ├── generate_changelog.sh # 更新日志脚本 ├── run_tests.sh # 测试运行脚本 └── lint_check.sh # 代码检查脚本这里有一个很关键的经验CLAUDE.md只做索引不做内容。也就是说项目入口文件里只写这个模板库本身的规则、如何使用各个命令、加载顺序不要把 review 的要求、重构的步骤全堆在里面。正确的做法是让入口文件做导航具体内容放到 commands 或 skills 子文件中。这样做的原因是上下文窗口有限而且 Claude 对长文件尾部的注意力会衰减。入口文件一屏能看完AI 就知道去哪找什么东西。一旦它需要 review就知道去commands/review.md里找详细清单而不是在入口文件里苦等回忆。3. CLAUDE.md 的编写要点从规则到约束一次写对3.1 项目级 CLAUDE.md重点是项目事实而非通用废话项目级的CLAUDE.md是每个仓库都必须有的文件。它描述的不是你应该写出清晰代码这种套话而是这个项目的客观事实。我的项目级文件模板一般长这样# 项目说明 这是一个基于 Vue 3 TypeScript 的后台管理系统。 使用 pnpm 作为包管理器Node 版本要求 18。 ## 技术栈 - 前端Vue 3.4, TypeScript 5.x, Pinia, Vue Router - 后端Node.js Express, Prisma ORM - 数据库PostgreSQL 15 ## 目录结构 src/ api/ # 接口请求封装 components/ # 公共组件 views/ # 页面视图 stores/ # 状态管理 utils/ # 工具函数 ## 编码规则 - 组件文件名使用 PascalCase如 UserCard.vue - 样式使用 Tailwind CSS禁止写全局样式覆盖 - API 请求全部走 src/api 下的封装禁止直接调用 fetch - 状态管理统一使用 Pinia禁止在组件内直接修改全局状态 ## 构建与测试命令 - 开发pnpm dev - 构建pnpm build - 测试pnpm test - Lintpnpm lint ## 禁止事项 - 禁止修改 src/api 的请求响应拦截逻辑 - 禁止在非 ./env 文件中硬编码环境变量 - 禁止引入新的 UI 组件库看起来平淡无奇但正是这些东西让 Claude Code 在绝大多数时间表现得像熟悉项目的同事而不是第一次见代码的外包程序员。尤其禁止事项这一节比任何正面规则都管用因为我发现模型对否定性约束的记忆权重比肯定性要求更高这正好帮我们守住项目的技术底线。需要注意的一点是项目规则变了同步更新这个文件的频率要跟上。我见过不少团队改技术栈了但 CLAUDE.md 还写着旧版框架AI 按着老规矩给出建议整段没法用。这东西必须当代码一样维护不是写完就完事。3.2 全局级 CLAUDE.md只放跨项目的稳定约定全局文件放在~/.claude/CLAUDE.md对所有项目生效。这意味着它只应该放永远成立的约定比如# 全局对话规则 - 对于不确定的需求先确认再执行不要自行假设。 - 输出代码时默认附带必要的注释中文注释。 - 回答问题时优先给出结论再展开解释。 - 涉及多个解决方案时用表格对比优劣最后给出推荐。这类内容在任何项目里都不会出错才值得放进全局文件。但我强烈建议不要放太多条。我曾经一股脑写了 20 条全局规则结果 AI 每次都像在做规则背诵测试回答问题时过度小心翼翼反而拖慢了效率。精简到五条以内效果反而最好。3.3 优化 prompt 的经验少用形容词多用列表和判定模板里的提示词不是越详细越好而是要结构化用列表代替段落用当...时执行...代替应该要...用禁止/除非/必须代替尽量不要/最好别比如我在 review 模板里写的是## Code Review 检查清单 按顺序逐项检查每一项给出通过/不通过/建议改进的结论 1. 变更文件是否超出任务范围 2. 是否有未处理的边界条件 3. 是否遵循项目的错误处理约定统一错误码、统一日志 4. 是否有明显的性能问题N1 查询、循环内请求接口 5. 是否有测试覆盖关键路径 6. 提交信息是否符合约定格式 输出格式 - 问题列表按严重程度排序 - 每一条问题给出文件:行号定位 - 最后给一个总体结论可以合并 / 修改后合并 / 打回这样输出非常规整你可以直接把它的结论贴到 PR 页面里当 Review 意见改动量极小。如果模板里只是写请认真审查代码AI 过一遍就回一句看起来没问题那 review 效果几乎等于零。4. slash commands 与 skills让模板从读变成用4.1 slash command 写法示例把固定流程变成一键呼叫.claude/commands/review.md就是一个 slash command在 Claude Code 对话窗口里输入/review它就会自动加载该文件并执行。下面是我实际的 review 模板完整内容--- description: 对当前分支进行代码审查 argument-hint: 可选指定审查范围如 src/components/UserCard.vue --- 执行代码审查任务。 1. 运行 git diff main...HEAD 获取变更内容 2. 按下方检查清单逐项审查变更代码 3. 每一项给出通过/不通过/建议改进的结论 ## 检查清单 - 变更范围是否控制合理 - 是否有破坏性变更数据库、API 协议、公共组件 - 错误处理是否符合项目统一模式 - 是否引入重复代码或可抽象逻辑 - 是否有明显性能问题 ## 输出格式 按以下格式输出 **审查范围**文件名 **问题列表** 1. **[严重/一般/建议]** 描述问题标注文件:行号 **总体结论**可以合并 / 修改后合并 / 打回 ## 注意事项 - 如果变更已经包含测试且测试通过重点检查逻辑完整性 - 对生成的代码不要假设执行环境不确定时标注需人工确认有了这个模板之后代码审查变成了一个高度标准化的流程而且不挑人、不挑状态同一个模板在任何人手里执行的结果都差不多。这对团队协作尤其重要——Review 质量不再依赖今天状态好不好。4.2 写 slash command 的排坑心得几个容易踩的坑先列出来第一description字段必填。没有描述的话在输入/时不会出现在命令列表里后面想不起来叫什么名字就只能翻文件。第二argument-hint字段写清楚AI 才能正确理解你给的参数。比如/refactor src/utils/date.ts如果模板里没有说明如何解析这个参数AI 可能把整句话当成变量名去搜文件。第三模板里尽量使用项目内已经存在的命令和路径用错了 AI 会一本正经地给你编一个不存在的命令。有时候它为了完成任务会自己补全想象出来的操作这种现象一旦出现在文件删除、依赖安装这类敏感操作上后果是很直接的。所以我要在调试和重构类模板里显式加上一句不确定的命令必须询问用户禁止自行猜测并执行。第四单个 command 的长度控制在 100 行以内。太长了 AI 会选择困难反而抓不住重点。如果你有非常复杂的流程建议拆成多个命令用第一个命令去调用后续命令。4.3 skills 和 commands 到底选哪个我的经验是区分标准很简单commands 用于执行固定流程skills 用于指导某个领域的任务思路。/review、/refactor、/test是 commands因为它们的核心是一串可执行的步骤目标是得到某个产物的输出。前端 Vue 开发、后端 Python 任务、数据库迁移是 skills因为它们提供的是某类任务的背景知识、注意事项和常见模式AI 拿到的是该领域的做事方法。skills 不用斜杠命令调用直接在对话里写用前端 Vue skill 来帮我实现这个页面AI 就会去.claude/skills/frontend-vue.md加载相关内容。这种区分方式能防止模板库变成一锅乱炖也方便后期维护。4.4 与脚本联动用 scripts 目录把本地能力接进模板模板文件毕竟只是文本真正要执行测试、lint、生成变更记录还是得靠本地脚本跑。模板的价值在于告诉 AI何时调用脚本、如何解读脚本输出。我的测试模板里就有这么一段运行测试 bash pnpm test -- --reporterjson如果测试失败根据 JSON 输出中的失败用例列表逐一分析先看是断言失败还是代码错误如果断言与需求不符检查需求理解是否正确如果是代码错误定位到堆栈中的第一个项目文件有了脚本做后端支撑AI 的凭空推理就少了很多——它能看到真实的测试结果而不是靠猜。实际效果是bug 定位准确率大幅提升因为 AI 能把错误信息和具体代码行对应起来。 ## 5. 实战实录用一套模板重建旧模块到底跑了多大差距 ### 5.1 场景一个旧用户管理模块重构 我拿自己一个实际项目做的对照测试。项目里有一个用户管理模块大概 15 个文件、3000 多行代码里面混杂着业务逻辑、UI 渲染、状态管理耦合严重。我用带模板和不带模板两种方式分别让 Claude Code 做重构效果差距非常明显。 不带模板时我在对话里输入帮我把用户管理模块重构一下代码太乱了。结果 AI 开始了自由发挥——它把我整个 src 目录扫了一遍然后建议可以重构成微前端架构同时还开始改起了无关模块的代码。这也不能全怪 AI提示词里太乱是非常主观的描述它只能猜什么叫不乱。 带模板时同样的场景我输入/refactor src/views/user-management模板会先让 AI 读取目录结构和现有代码然后按既定的重构步骤执行先梳理现状并输出模块依赖图、列出耦合点再逐层重构重构过程中不得改动公共 API 签名最后运行完整的测试套件验证。 ### 5.2 带模板执行时AI 的输出流程 实际执行过程中AI 的输出大致是这样的 - 先输出一份文件清单和依赖关系说明明确改动范围 - 每个文件改动前先说明为什么要改、怎么改 - 重构期间保持接口签名不变只改内部实现 - 完成后自动跑测试根据测试结果再迭代一次 - 最后输出一份变更摘要按文件列出改动点和潜在风险 整个过程像一份相当规范的技术周报每步都有依据出了偏差我能及时发现。对比之下不带模板时 AI 改完代码我连 diff 都看得头晕因为改动面太大又没留过程说明哪块是重写哪块是挪位置都要猜。 ### 5.3 为什么这套流程能跑通关键在哪 核心在于**模板把 AI 的推理路径锁定了**。重构这个任务最大的风险不是模型能力不足而是方向跑偏。模板通过强约束的步骤让 AI 每一步都产出中间结果用户能看到它在干什么、打算干什么。一旦发现偏离可以随时打断纠偏而不是等它改完几百行代码才发现方向完全错。 效率上带模板完成整个重构大概花了一小时左右而不带模板的第一版花了两小时其中有一半时间在回滚和澄清需求。哪怕把写模板本身的时间算进去第一周就已经回本。 ## 6. 设计模板时最容易踩的坑以及我的避坑清单 ### 6.1 模板贪多求全反而失效 初期我做的一个错误是试图把一个模板覆盖所有场景。比如写一个通用开发模板既管重构、又管写测试、还管提交信息结果 AI 根本判断不了当前到底该按哪条规则执行——输出像是从三套模板里各取一段拼接的。 后面改成每个模板只负责一件事规则就清爽了/review 只管代码审查/refactor 只管重构/test 只管测试生成。模板之间可以互相引用比如重构完成后自动调用测试模板去跑验证但每个模板文件的职责边界必须清晰。 这个经验同样适用于模板内部的段落安排。一个 templates 文件内部也要按触发条件 - 执行步骤 - 输出格式 - 注意事项四个模块来分乱写乱放的结果就是 AI 抓不住主干。 ### 6.2 不写版本信息模板烂了都不知道 模板库维护过程中我养成了一个习惯每个模板文件的头部都维护 version 和 last-updated 字段。这不是形式主义因为模板本身会伴随项目技术栈的调整、流程规范的变化而迭代如果不知道当前是否最新版使用者很容易拿旧模板套新项目。 更推荐的做法是模板和代码一样走 git 管理。每次修改模板都写提交信息比如 review: 增加对数据库迁移文件的审查规则这样回溯起来非常方便。如果你在团队里推行模板文化这个做法尤其重要——不然你根本说不清当前每人用的模板是不是同一个版本。 ### 6.3 过度依赖模板忽略人的判断 这里想委婉地给一句提醒模板能大幅提高效率但它只是工具不能替代人的代码品味和架构判断。我在实际使用中见过不少团队把模板当成银弹把什么都交给 AI 自动做结果重构出来的代码结构确实符合规则但业务语义别扭、可读性平庸。 正确的姿势是**模板负责不出错人负责做得好**。AI 按模板跑完你仍然需要看一遍改动逻辑把不合理的地方人工调整。模板库迭代了半年之后我自己最大的变化是从每一行都要盯着改变成了模板跑完看关键节点剩余信任交给测试兜底这个度要靠自己根据项目情况摸索。 ### 6.4 常见问题速查表 | 问题 | 现象 | 原因 | 解决方法 | |---|---|---|---| | AI 忽略模板规则 | 输出不符合既定格式 | 模板过长关键约束被稀释 | 精简篇幅核心规则置顶 | | 执行了错误命令 | 出现不明文件改动 | 命令描述太模糊 | 模板内明确不确定先询问 | | 模板内容过时 | 一直按旧规范执行 | 缺少维护机制 | 模板纳入 git 管理定期审查 | | 多个模板互相冲突 | 规则覆盖或矛盾 | 职责边界不清 | 检查各模板的触发条件是否重叠 | | 上下文窗口报警 | 模板文件太多 | 加载内容超过模型窗口 | 按需加载减少全量注入 | 我自己几乎每次遭遇AI 行为异常后去翻都能溯源到某条模板规则写得太模糊或者过时了。所以如果哪天你觉得 AI 在同一个项目里表现突然变差第一件事去翻最近有没有人改过 CLAUDE.md——比重新调节 prompt 有用得多。 ## 7. 最后的几条私人心得 模板库做到现在我最大的感受是**写模板的投入产出比是 Claude Code 所有用法里最高的**。它不像某个具体功能需要反复学习和试错模板就是把你已经掌握的工作方法固化下来让 AI 替你执行的时候不至于走样。每写一个模板就相当于给未来的自己招了一个熟悉项目规则的外包工程师它干活之前先读了你沉淀好的员工手册。 个人在实际使用中还有两个小习惯值得分享。第一个是收尾时一定让 AI 输出变更摘要把改了什么、为什么改、影响了哪些调用方讲清楚这个摘要直接就是 Commit Message 的底稿比 git diff 读起来高效太多。第二个是每个月花二十分钟翻一遍模板库删掉过期内容、补上新踩坑得出的规则让模板库保持苗条——一个塞满过时约束的模板库比没有模板更糟因为它会让 AI 拿着过时路线图带路。 如果你现在刚开始上手 Claude Code我的建议也很简单别急着写一堆大而全的模板先挑你最高频、最痛苦的那一个场景比如代码审查或者提交信息生成写一个 50 行以内的模板用起来。跑顺一个再扩下一个。模板库靠积累不靠一次规划。等攒到十个八个后你就能体会到那种开了个好头的感觉——往后每一次新会话AI 都像那个熟悉你项目、懂你偏好的老搭档而不是每次都要重新教的实习生。 Claude Code模板库：固化上下文框架，告别重复提示词
1. 先搞清楚claude-code-templates 到底解决了什么问题最近在重构一个老项目时我干了一件之前一直懒得干的事把所有常用的 Claude Code 提示词、工作流、代码审查清单、任务脚本全部整理成了一个模板库。整理完之后最大的感受是——这一周省下的时间比我过去三个月零零散散写提示词花掉的时间还多。如果你用过 Claude Code 这类 AI 编程工具大概会有同感功能很强大但每次新建会话都要重新交代一遍项目背景、编码规范、任务边界有时候写了一大段话进去AI 还是理解偏了。不是模型不行是你没给它一个稳定的上下文框架。而 claude-code-templates 说白了就是把这套上下文框架固化成文件让 AI 每次开工前自动加载一套成熟的工作模板。它能解决几个非常现实的问题告别每次重复敲提示词。项目背景、技术栈、目录结构、代码风格这些信息写进模板后自动生效不用每次重述。让 AI 的输出更稳定。同一个任务不同时间、不同会话执行的思路能保持基本一致不会这次给你重构、下次给你重写。约束 AI 不越界。模板里写明不可修改的文件禁止执行的命令这类边界条款能大幅减少 AI 擅自改代码带来的麻烦。沉淀团队经验。新人接手项目时把这些模板文件一读马上就能理解团队约定和常见坑比翻文档高效得多。适合谁参考如果你是 Claude Code 的重度用户每天靠它写代码、改 bug、做代码审查那你肯定用得上。如果你刚开始接触这类工具但已经被每次都要重新解释背景折磨得不耐烦了这篇文章同样值得看完。下文全部基于我个人已经跑通的一套模板方案列出了文件结构、核心写法、真实效果可以直接照抄也可以根据自己项目调整。2. 模板库的核心设计思路分类、分层、给 AI 立规矩2.1 先想清楚你要沉淀哪些可复用资产我在整理模板之前先列了一个需求清单发现日常使用 Claude Code 时真正反复消耗精力的场景无非这几类项目级规则代码风格、提交规范、禁止事项任务级流程重构、加功能、修 bug、写测试、做 Code Review单次操作执行命令、批量替换、解释代码、提交信息生成专场景模板前端、后端、数据脚本等不同领域的切入点对应这些场景我将模板库分成四个层级层级落地文件作用范围加载方式全局规则~/.claude/CLAUDE.md所有项目、所有会话自动加载项目规则CLAUDE.md当前项目自动加载共享命令.claude/commands/*.md当前项目slash command 手动调用一次性脚本.claude/skills/*.md按需调用输入 prompt 时引用自动加载的是前两类它们会进入 Claude 的系统提示词构成最基础的上下文。后两类是按需拉取的避免一次加载太多内容导致 AI 分不清重点。这个分层的核心逻辑是静态规则自动生效动态命令按需调用。把所有规则一股脑丢进全局文件里AI 会消化不良——它对会话早期出现的内容权重最高如果开头塞进去 500 行无用信息真正重要的规范反而会被稀释。分层之后全局文件只保留永远正确的内容项目文件只管当前仓库的具体约定剩下的统统交给按需加载。2.2 关键设计为每个模板设置触发条件与退出条件这是我踩了无数坑之后总结出来的最重要的一条经验。早期我的模板就是一段话让 AI 做完任务就行结果它经常跑偏——加一个字段能把相邻的三个模块全部重构一遍写个单元测试能给整个项目装上十几个新的依赖。后来我在每个模板开头都加了两个字段当且仅当和除非。举个例子我的重构模板开头是这样写的## 重构任务 当且仅当用户明确提出重构/优化/改善某模块时本模板生效。 除非 - 用户没有指定具体模块或文件范围 - 重构会破坏现有测试 - 涉及跨模块的大范围改动 以上情况出现时必须先向用户确认范围再继续执行。就是这样一个简单的当且仅当 除非结构把 AI 的自作主张概率降了一半以上。本质上是给 AI 一个行为判定逻辑什么时候该动手什么时候该停下来问人。这比单纯写请小心重构、不要乱改这种模糊提示要有效得多因为程序化的判定条件更容易被模型理解和遵守。2.3 目录怎么摆加载顺序怎么定我的模板库采用了一个很直接的目录结构claude-code-templates/ ├── CLAUDE.md # 项目入口全局规范 ├── docs/ │ ├── 01-quickstart.md # 快速上手说明 │ ├── 02-architecture.md # 架构说明 │ └── 03-workflows.md # 工作流总览 ├── commands/ │ ├── review.md # Code Review 指令 │ ├── refactor.md # 重构指令 │ ├── test.md # 测试生成指令 │ ├── commit.md # 提交信息生成指令 │ └── debug.md # Debug 会话指令 ├── skills/ │ ├── frontend-vue.md # Vue 前端任务 │ ├── backend-python.md # Python 后端任务 │ ├── database-migration.md # 数据库迁移任务 │ └── api-design.md # API 设计任务 └── scripts/ ├── generate_changelog.sh # 更新日志脚本 ├── run_tests.sh # 测试运行脚本 └── lint_check.sh # 代码检查脚本这里有一个很关键的经验CLAUDE.md只做索引不做内容。也就是说项目入口文件里只写这个模板库本身的规则、如何使用各个命令、加载顺序不要把 review 的要求、重构的步骤全堆在里面。正确的做法是让入口文件做导航具体内容放到 commands 或 skills 子文件中。这样做的原因是上下文窗口有限而且 Claude 对长文件尾部的注意力会衰减。入口文件一屏能看完AI 就知道去哪找什么东西。一旦它需要 review就知道去commands/review.md里找详细清单而不是在入口文件里苦等回忆。3. CLAUDE.md 的编写要点从规则到约束一次写对3.1 项目级 CLAUDE.md重点是项目事实而非通用废话项目级的CLAUDE.md是每个仓库都必须有的文件。它描述的不是你应该写出清晰代码这种套话而是这个项目的客观事实。我的项目级文件模板一般长这样# 项目说明 这是一个基于 Vue 3 TypeScript 的后台管理系统。 使用 pnpm 作为包管理器Node 版本要求 18。 ## 技术栈 - 前端Vue 3.4, TypeScript 5.x, Pinia, Vue Router - 后端Node.js Express, Prisma ORM - 数据库PostgreSQL 15 ## 目录结构 src/ api/ # 接口请求封装 components/ # 公共组件 views/ # 页面视图 stores/ # 状态管理 utils/ # 工具函数 ## 编码规则 - 组件文件名使用 PascalCase如 UserCard.vue - 样式使用 Tailwind CSS禁止写全局样式覆盖 - API 请求全部走 src/api 下的封装禁止直接调用 fetch - 状态管理统一使用 Pinia禁止在组件内直接修改全局状态 ## 构建与测试命令 - 开发pnpm dev - 构建pnpm build - 测试pnpm test - Lintpnpm lint ## 禁止事项 - 禁止修改 src/api 的请求响应拦截逻辑 - 禁止在非 ./env 文件中硬编码环境变量 - 禁止引入新的 UI 组件库看起来平淡无奇但正是这些东西让 Claude Code 在绝大多数时间表现得像熟悉项目的同事而不是第一次见代码的外包程序员。尤其禁止事项这一节比任何正面规则都管用因为我发现模型对否定性约束的记忆权重比肯定性要求更高这正好帮我们守住项目的技术底线。需要注意的一点是项目规则变了同步更新这个文件的频率要跟上。我见过不少团队改技术栈了但 CLAUDE.md 还写着旧版框架AI 按着老规矩给出建议整段没法用。这东西必须当代码一样维护不是写完就完事。3.2 全局级 CLAUDE.md只放跨项目的稳定约定全局文件放在~/.claude/CLAUDE.md对所有项目生效。这意味着它只应该放永远成立的约定比如# 全局对话规则 - 对于不确定的需求先确认再执行不要自行假设。 - 输出代码时默认附带必要的注释中文注释。 - 回答问题时优先给出结论再展开解释。 - 涉及多个解决方案时用表格对比优劣最后给出推荐。这类内容在任何项目里都不会出错才值得放进全局文件。但我强烈建议不要放太多条。我曾经一股脑写了 20 条全局规则结果 AI 每次都像在做规则背诵测试回答问题时过度小心翼翼反而拖慢了效率。精简到五条以内效果反而最好。3.3 优化 prompt 的经验少用形容词多用列表和判定模板里的提示词不是越详细越好而是要结构化用列表代替段落用当...时执行...代替应该要...用禁止/除非/必须代替尽量不要/最好别比如我在 review 模板里写的是## Code Review 检查清单 按顺序逐项检查每一项给出通过/不通过/建议改进的结论 1. 变更文件是否超出任务范围 2. 是否有未处理的边界条件 3. 是否遵循项目的错误处理约定统一错误码、统一日志 4. 是否有明显的性能问题N1 查询、循环内请求接口 5. 是否有测试覆盖关键路径 6. 提交信息是否符合约定格式 输出格式 - 问题列表按严重程度排序 - 每一条问题给出文件:行号定位 - 最后给一个总体结论可以合并 / 修改后合并 / 打回这样输出非常规整你可以直接把它的结论贴到 PR 页面里当 Review 意见改动量极小。如果模板里只是写请认真审查代码AI 过一遍就回一句看起来没问题那 review 效果几乎等于零。4. slash commands 与 skills让模板从读变成用4.1 slash command 写法示例把固定流程变成一键呼叫.claude/commands/review.md就是一个 slash command在 Claude Code 对话窗口里输入/review它就会自动加载该文件并执行。下面是我实际的 review 模板完整内容--- description: 对当前分支进行代码审查 argument-hint: 可选指定审查范围如 src/components/UserCard.vue --- 执行代码审查任务。 1. 运行 git diff main...HEAD 获取变更内容 2. 按下方检查清单逐项审查变更代码 3. 每一项给出通过/不通过/建议改进的结论 ## 检查清单 - 变更范围是否控制合理 - 是否有破坏性变更数据库、API 协议、公共组件 - 错误处理是否符合项目统一模式 - 是否引入重复代码或可抽象逻辑 - 是否有明显性能问题 ## 输出格式 按以下格式输出 **审查范围**文件名 **问题列表** 1. **[严重/一般/建议]** 描述问题标注文件:行号 **总体结论**可以合并 / 修改后合并 / 打回 ## 注意事项 - 如果变更已经包含测试且测试通过重点检查逻辑完整性 - 对生成的代码不要假设执行环境不确定时标注需人工确认有了这个模板之后代码审查变成了一个高度标准化的流程而且不挑人、不挑状态同一个模板在任何人手里执行的结果都差不多。这对团队协作尤其重要——Review 质量不再依赖今天状态好不好。4.2 写 slash command 的排坑心得几个容易踩的坑先列出来第一description字段必填。没有描述的话在输入/时不会出现在命令列表里后面想不起来叫什么名字就只能翻文件。第二argument-hint字段写清楚AI 才能正确理解你给的参数。比如/refactor src/utils/date.ts如果模板里没有说明如何解析这个参数AI 可能把整句话当成变量名去搜文件。第三模板里尽量使用项目内已经存在的命令和路径用错了 AI 会一本正经地给你编一个不存在的命令。有时候它为了完成任务会自己补全想象出来的操作这种现象一旦出现在文件删除、依赖安装这类敏感操作上后果是很直接的。所以我要在调试和重构类模板里显式加上一句不确定的命令必须询问用户禁止自行猜测并执行。第四单个 command 的长度控制在 100 行以内。太长了 AI 会选择困难反而抓不住重点。如果你有非常复杂的流程建议拆成多个命令用第一个命令去调用后续命令。4.3 skills 和 commands 到底选哪个我的经验是区分标准很简单commands 用于执行固定流程skills 用于指导某个领域的任务思路。/review、/refactor、/test是 commands因为它们的核心是一串可执行的步骤目标是得到某个产物的输出。前端 Vue 开发、后端 Python 任务、数据库迁移是 skills因为它们提供的是某类任务的背景知识、注意事项和常见模式AI 拿到的是该领域的做事方法。skills 不用斜杠命令调用直接在对话里写用前端 Vue skill 来帮我实现这个页面AI 就会去.claude/skills/frontend-vue.md加载相关内容。这种区分方式能防止模板库变成一锅乱炖也方便后期维护。4.4 与脚本联动用 scripts 目录把本地能力接进模板模板文件毕竟只是文本真正要执行测试、lint、生成变更记录还是得靠本地脚本跑。模板的价值在于告诉 AI何时调用脚本、如何解读脚本输出。我的测试模板里就有这么一段运行测试 bash pnpm test -- --reporterjson如果测试失败根据 JSON 输出中的失败用例列表逐一分析先看是断言失败还是代码错误如果断言与需求不符检查需求理解是否正确如果是代码错误定位到堆栈中的第一个项目文件有了脚本做后端支撑AI 的凭空推理就少了很多——它能看到真实的测试结果而不是靠猜。实际效果是bug 定位准确率大幅提升因为 AI 能把错误信息和具体代码行对应起来。 ## 5. 实战实录用一套模板重建旧模块到底跑了多大差距 ### 5.1 场景一个旧用户管理模块重构 我拿自己一个实际项目做的对照测试。项目里有一个用户管理模块大概 15 个文件、3000 多行代码里面混杂着业务逻辑、UI 渲染、状态管理耦合严重。我用带模板和不带模板两种方式分别让 Claude Code 做重构效果差距非常明显。 不带模板时我在对话里输入帮我把用户管理模块重构一下代码太乱了。结果 AI 开始了自由发挥——它把我整个 src 目录扫了一遍然后建议可以重构成微前端架构同时还开始改起了无关模块的代码。这也不能全怪 AI提示词里太乱是非常主观的描述它只能猜什么叫不乱。 带模板时同样的场景我输入/refactor src/views/user-management模板会先让 AI 读取目录结构和现有代码然后按既定的重构步骤执行先梳理现状并输出模块依赖图、列出耦合点再逐层重构重构过程中不得改动公共 API 签名最后运行完整的测试套件验证。 ### 5.2 带模板执行时AI 的输出流程 实际执行过程中AI 的输出大致是这样的 - 先输出一份文件清单和依赖关系说明明确改动范围 - 每个文件改动前先说明为什么要改、怎么改 - 重构期间保持接口签名不变只改内部实现 - 完成后自动跑测试根据测试结果再迭代一次 - 最后输出一份变更摘要按文件列出改动点和潜在风险 整个过程像一份相当规范的技术周报每步都有依据出了偏差我能及时发现。对比之下不带模板时 AI 改完代码我连 diff 都看得头晕因为改动面太大又没留过程说明哪块是重写哪块是挪位置都要猜。 ### 5.3 为什么这套流程能跑通关键在哪 核心在于**模板把 AI 的推理路径锁定了**。重构这个任务最大的风险不是模型能力不足而是方向跑偏。模板通过强约束的步骤让 AI 每一步都产出中间结果用户能看到它在干什么、打算干什么。一旦发现偏离可以随时打断纠偏而不是等它改完几百行代码才发现方向完全错。 效率上带模板完成整个重构大概花了一小时左右而不带模板的第一版花了两小时其中有一半时间在回滚和澄清需求。哪怕把写模板本身的时间算进去第一周就已经回本。 ## 6. 设计模板时最容易踩的坑以及我的避坑清单 ### 6.1 模板贪多求全反而失效 初期我做的一个错误是试图把一个模板覆盖所有场景。比如写一个通用开发模板既管重构、又管写测试、还管提交信息结果 AI 根本判断不了当前到底该按哪条规则执行——输出像是从三套模板里各取一段拼接的。 后面改成每个模板只负责一件事规则就清爽了/review 只管代码审查/refactor 只管重构/test 只管测试生成。模板之间可以互相引用比如重构完成后自动调用测试模板去跑验证但每个模板文件的职责边界必须清晰。 这个经验同样适用于模板内部的段落安排。一个 templates 文件内部也要按触发条件 - 执行步骤 - 输出格式 - 注意事项四个模块来分乱写乱放的结果就是 AI 抓不住主干。 ### 6.2 不写版本信息模板烂了都不知道 模板库维护过程中我养成了一个习惯每个模板文件的头部都维护 version 和 last-updated 字段。这不是形式主义因为模板本身会伴随项目技术栈的调整、流程规范的变化而迭代如果不知道当前是否最新版使用者很容易拿旧模板套新项目。 更推荐的做法是模板和代码一样走 git 管理。每次修改模板都写提交信息比如 review: 增加对数据库迁移文件的审查规则这样回溯起来非常方便。如果你在团队里推行模板文化这个做法尤其重要——不然你根本说不清当前每人用的模板是不是同一个版本。 ### 6.3 过度依赖模板忽略人的判断 这里想委婉地给一句提醒模板能大幅提高效率但它只是工具不能替代人的代码品味和架构判断。我在实际使用中见过不少团队把模板当成银弹把什么都交给 AI 自动做结果重构出来的代码结构确实符合规则但业务语义别扭、可读性平庸。 正确的姿势是**模板负责不出错人负责做得好**。AI 按模板跑完你仍然需要看一遍改动逻辑把不合理的地方人工调整。模板库迭代了半年之后我自己最大的变化是从每一行都要盯着改变成了模板跑完看关键节点剩余信任交给测试兜底这个度要靠自己根据项目情况摸索。 ### 6.4 常见问题速查表 | 问题 | 现象 | 原因 | 解决方法 | |---|---|---|---| | AI 忽略模板规则 | 输出不符合既定格式 | 模板过长关键约束被稀释 | 精简篇幅核心规则置顶 | | 执行了错误命令 | 出现不明文件改动 | 命令描述太模糊 | 模板内明确不确定先询问 | | 模板内容过时 | 一直按旧规范执行 | 缺少维护机制 | 模板纳入 git 管理定期审查 | | 多个模板互相冲突 | 规则覆盖或矛盾 | 职责边界不清 | 检查各模板的触发条件是否重叠 | | 上下文窗口报警 | 模板文件太多 | 加载内容超过模型窗口 | 按需加载减少全量注入 | 我自己几乎每次遭遇AI 行为异常后去翻都能溯源到某条模板规则写得太模糊或者过时了。所以如果哪天你觉得 AI 在同一个项目里表现突然变差第一件事去翻最近有没有人改过 CLAUDE.md——比重新调节 prompt 有用得多。 ## 7. 最后的几条私人心得 模板库做到现在我最大的感受是**写模板的投入产出比是 Claude Code 所有用法里最高的**。它不像某个具体功能需要反复学习和试错模板就是把你已经掌握的工作方法固化下来让 AI 替你执行的时候不至于走样。每写一个模板就相当于给未来的自己招了一个熟悉项目规则的外包工程师它干活之前先读了你沉淀好的员工手册。 个人在实际使用中还有两个小习惯值得分享。第一个是收尾时一定让 AI 输出变更摘要把改了什么、为什么改、影响了哪些调用方讲清楚这个摘要直接就是 Commit Message 的底稿比 git diff 读起来高效太多。第二个是每个月花二十分钟翻一遍模板库删掉过期内容、补上新踩坑得出的规则让模板库保持苗条——一个塞满过时约束的模板库比没有模板更糟因为它会让 AI 拿着过时路线图带路。 如果你现在刚开始上手 Claude Code我的建议也很简单别急着写一堆大而全的模板先挑你最高频、最痛苦的那一个场景比如代码审查或者提交信息生成写一个 50 行以内的模板用起来。跑顺一个再扩下一个。模板库靠积累不靠一次规划。等攒到十个八个后你就能体会到那种开了个好头的感觉——往后每一次新会话AI 都像那个熟悉你项目、懂你偏好的老搭档而不是每次都要重新教的实习生。