★ FEATURED ARTICLE 写模板这事儿我琢磨了好一阵子才摸到门道。刚开始用 Claude Code 的时候我跟大多数人一样想到什么就临时敲一段话丢给它让它改 bug、写测试、做 code review。用着用着就发现问题了每次新建会话它对项目一无所知我得把技术栈、目录结构、编码规范重新解释一遍。碰上复杂的任务解释背景的时间比干活的时间还长而且它偶尔还会给出跟项目风格完全不一致的代码。后来我把这套 claude-code-templates 整理了出来——说白了一句话把 AI 当成团队里一个记性很差但学习能力很强的同事你得给它一份入职手册还得把经常布置的任务写成标准作业流程。这篇文章就围绕这套模板体系展开从上下文机制、主模板设计、任务提示词模板到团队复用和调优经验一步步说清楚怎么搭一套真正能用的 Claude Code 模板库。适合刚入手 Claude Code 的开发者也适合已经在用但觉得输出不稳定的人。1. 模板不是 .md 文件堆砌先搞懂 Claude Code 的上下文机制很多人对模板有个误区觉得不就是写几个 markdown 文件放那儿嘛。其实模板能不能起作用完全取决于你对 Claude Code 上下文机制的理解决到位没有。这步没搞懂后面写的模板大概率是废的。1.1 每次会话都是一张白纸CLAUDE.md 就是入职手册Claude Code 在工作时会自动加载项目根目录下的 CLAUDE.md把它作为整个会话的背景知识。这就好比一个新同事入职你先甩给他一份员工手册他后面干的所有活都以这份手册为基准。这里有个关键点很容易被忽略Claude Code 的会话记忆是不跨会话的。你上周跟它聊了十个回合这周再打开一个新会话它什么都记不得。很多人抱怨AI 怎么这么笨昨天刚说过又忘了其实不是笨是机制如此。我自己的项目里 CLAUDE.md 的开头几行是这样写的# CLAUDE.md ## 项目概述 这是一个基于 Next.js 14 的内容管理后台主要服务内部运营团队。 核心业务是文章发布、素材管理和数据看板。 ## 技术栈 - 前端框架Next.js 14App Router - UI 组件库shadcn/ui Tailwind CSS - 数据层Prisma PostgreSQL - 认证方式NextAuth.js - 包管理器pnpm这样一来每次新会话我只需要说帮我写一个素材上传的 API 接口它就知道要用 Prisma 操作 PostgreSQL、按 App Router 的路由约定来组织代码、用 pnpm 装依赖完全不需要我重复交代。1.2 上下文窗口有限模板的目的是精准投喂大模型有上下文长度限制Claude Code 自然也不例外。虽然现在的窗口比早期大了不少但你把几千行项目代码全塞进去既不现实也没必要。这里有个生活化的类比CLAUDE.md 不是给 AI 看的完整技术文档而是酒店前台的那张速查卡——酒店有多少间房、早餐几点供应、Wi-Fi 密码是多少、紧急电话打哪个这些高频信息放在最前面。至于每间房的装修图纸、管道结构图那是需要的时候再去资料室翻的东西不会提前全摆在柜台上。实际使用中我遵循三条投喂原则高频信息优先每个任务都会用到的内容技术栈、目录约定、命令放在最前面。低频信息不塞具体某个模块的设计细节、某段历史决策原因等做相关任务时靠提示词临时补充。动态信息占位比如当前分支、当前版本号这类会变的信息别写进 CLAUDE.md写进当次提示词里。1.3 子目录 CLAUDE.md局部上下文优于全局堆叠除了根目录的 CLAUDE.mdClaude Code 也支持在子目录放 CLAUDE.md会话中如果你把工作目录切到那个子目录或者涉及的文件在那个子目录下对应的 CLAUDE.md 也会被加载。这个机制我越用越喜欢。拿一个 monorepo 项目举例根目录的 CLAUDE.md 只写整体架构和通用规范packages/api 下的 CLAUDE.md 写 API 层的专有约定packages/web 下的 CLAUDE.md 写前端专属规则。这样每个层级的 AI 都能获得刚刚好的上下文既不用背一大堆无关信息也不会漏掉关键约束。2. CLAUDE.md 主模板的骨架一份能让 AI 真正理解项目的配置明确了上下文机制接下来看看我实际在用的 CLAUDE.md 主模板。它不是随手写的而是经过好几个项目迭代沉淀下来的骨架每个区块都有它存在的理由。2.1 项目概述一句话讲清楚 这个项目到底在做什么很多人写项目概述喜欢写又长又虚的句子比如本项目是公司数字化转型的核心平台为业务方提供一站式解决方案。这种话对 AI 一点用都没有。好的概述应该像产品经理的电梯演讲这个项目服务谁、解决什么问题、核心功能是什么。我自己的写法是## 项目概述 这是一个面向电商卖家的小程序数据分析工具帮助中小卖家快速查看 店铺核心指标GMV、转化率、退款率的日/周/月趋势。 目标用户是非技术背景的运营人员所以所有导出文件的命名规范 必须使用中文界面文案不允许出现英文缩写。最后一句导出文件用中文命名、界面不要英文缩写就是典型的暗规则你不写进模板AI 百分百会按自己的默认习惯来。2.2 技术栈说明具体到版本和关键选型原因技术栈区块最怕写得太笼统。只写前端 React 后端 Node.js等于没写。我整理了一份更可操作的写法## 技术栈 - 前端框架React 18使用 Vite 构建不使用 Next.js - 语言TypeScript 5.x必须开启 strict 模式 - 请求库axios统一封装在 src/api 目录下 - 状态管理zustand禁止使用 redux - UI 组件公司内部 ac-ui 组件库禁止引入 antd - 测试工具vitest testing-library/react注意这里面藏着好几个禁止。这些负面清单比正面清单更有价值因为它们直接把 AI 最可能踩的坑堵上了。实际开发中你会发现AI 默认会往大路货的技术选型上靠你若不明确禁止 antd、不明确说不用 redux它隔三差五就会给你冒出来。2.3 常用命令与脚本让 AI 不需要猜怎么跑项目Claude Code 能执行 shell 命令但它不可能知道你项目里 package.json 的 scripts 长什么样。与其等它跑错命令再去纠正不如直接在模板里写清楚## 常用命令 - 安装依赖pnpm install - 启动开发服务器pnpm dev默认端口 3000 - 构建生产包pnpm build - 运行测试pnpm test单测 / pnpm test:e2e端到端 - 代码检查pnpm linteslint prettier 一起跑 - 数据库迁移pnpm prisma:migrate ## 注意事项 - 不要使用 npm 或 yarn 安装依赖项目统一用 pnpm - 启动服务前先确认 .env.local 存在缺失时复制 .env.example这段信息对于 AI 执行帮我看看为什么测试跑不过这类任务格外重要。没有命令清单它会自作主张用 npm run test或者找不到环境变量文件导致报错。2.4 目录结构与代码约定比规范文档更实用的存在目录结构这块不要求完整遍历每个文件夹写清楚分层逻辑就够。以我常写的后端服务为例## 目录结构 - src/routes路由定义每个业务模块一个文件 - src/controllers业务控制层只做参数校验和调用 service - src/services核心业务逻辑层禁止直接操作数据库 - src/models数据库模型定义Prisma schema - src/utils工具函数纯函数为主 ## 代码约定 - controller 返回格式统一为 { code, data, message } - service 层错误统一抛 BusinessError由全局错误处理器兜底 - 所有金额字段用 number单位分禁止出现浮点精度问题 - 文件命名模块名 层级后缀如 user.controller.ts这些约定不是写在 wiki 里吃灰的文档而是 AI 每次写代码都要参照的基准。有了它AI 生成的代码天然符合项目现有风格code review 的时候省一大半口舌。2.5 完成定义DoD告诉 AI 干到什么程度算真正干完这是我最想安利的一个区块。AI 经常会出现做完 A 忘了 B 的情况比如让你改完接口顺手更新接口文档大部分时候它改完代码就停了。在 CLAUDE.md 里定义好通用完成标准能大幅减少这类遗漏## 完成定义 - 代码通过 lint 和类型检查pnpm lint / pnpm typecheck - 新功能必须补充对应的单测覆盖率不低于 80% - 涉及接口变更时同步更新 docs/api.md - 新增环境变量时同步更新 .env.example - 所有 console.log 清理干净调试代码不得提交这个区块把代码写完和任务完成之间的距离拉平了。AI 在执行任务时会有一个自我检查的环节把 DoD 逐条对照而不是交出一坨只实现了一半的代码。3. 按任务拆分的提示词模板库把高频操作变成标准动作CLAUDE.md 解决的是AI 懂不懂项目的问题。但实际使用中还有另一类问题任务本身描述不清楚。我早期最常犯的错是把需求写得太糙比如帮我写个列表页结果它出来的东西跟我的预期差了十万八千里。后来我养成了一个习惯给高频任务建立标准提示词模板。每个模板用一个 markdown 文件存起来用的时候复制出来替换掉关键占位符就行。3.1 代码审查模板从看看这段代码到系统性 check帮我 review 一下这段代码这种话太模糊了AI 只会泛泛地说几句代码写的很清晰、建议补充注释。我的审查模板长这样请你以资深后端工程师的视角对以下代码进行审查。 代码文件{粘贴代码或指定文件路径} 所属模块{模块名} 本次改动目的{一句话描述} 审查时重点检查以下维度 1. 正确性逻辑是否有边界条件遗漏、并发问题、异常路径缺失 2. 安全性是否有注入风险、敏感信息泄露、权限校验缺失 3. 性能是否存在不必要的循环嵌套、N1 查询、内存浪费 4. 可维护性命名、函数拆分、注释质量是否符合项目约定见 CLAUDE.md 5. 测试覆盖现有测试是否覆盖了核心分支 输出格式 - 按严重程度分三档P0必须修、P1建议修、P2可选优化 - 每个问题给出位置、原因、建议改法 - 最后给一个总体评价100 分制并说明扣分原因用这个模板之后它给出的审查意见质量明显上了一个档。关键点在于给了检查维度和输出格式AI 知道你要什么就能按图索骥地输出。3.2 测试生成模板让 AI 先列策略再写用例写测试是 AI 很擅长的活但它有一个老毛病喜欢挑最简单、最没价值的分支来测真正关键的边界反而漏掉。我的对策是强制它先出测试策略再动手你负责为以下函数/模块编写单元测试。 代码位置{路径} 核心逻辑描述{两三句话} 请先输出你的测试策略markdown 格式 - 需要覆盖的业务场景 - 边界条件清单 - 异常输入处理方式 - 需要用到的 mock 点 测试策略确认后再编写具体测试代码。测试代码要求 - 每个用例独立不依赖执行顺序 - 断言要具体不写无意义的快照断言 - 涉及异步操作时用 waitFor / findBy 而非固定 sleep - 遵循项目现有的测试风格命名、文件组织见 CLAUDE.md这个先策略后代码的设计看着多了一步实际能省下大量返工时间。如果 AI 的策略方向不对你在它动笔前就能纠正而不是等它写出一堆废用例再去改。3.3 Bug 修复模板先定位根因再动手禁止盲猜改法AI 修 bug 最恐怖的行为是看到报错信息直接猜一个原因改一行代码然后跟你说应该好了。它不会去验证也不会思考改动可能引入的副作用。Bug 修复模板就是为了治这个病请帮我排查并修复一个问题。 问题描述{报错信息 / 异常现象 / 复现步骤} 触发环境{浏览器版本 / Node 版本 / 是否 Docker} 相关代码{文件路径尽量精确} 请严格按以下步骤执行 1. 先分析可能的原因列出至少 3 个假设按概率排序 2. 对每个假设说明你的验证方式查看日志加断点写测试复现 3. 执行验证缩小范围最终定位根因后给出解释 4. 修复代码说明你的改动思路和影响范围 5. 新增一个回归测试确保类似问题不会再次出现 禁止在未定位根因前直接修改代码输出。第五步新增回归测试是这个模板的灵魂。没有它AI 修完 bug 你还要担心它偷偷破坏了别的功能有它至少核心问题被锁死了。3.4 重构模板行为保持不变是第一原则重构任务最怕的就是 AI 顺手改了逻辑。我的重构模板开篇就立规矩请对以下代码做重构目标是提升可读性和可维护性。 代码位置{路径} 重构动机{为什么要做圈复杂度高重复代码多命名混乱} 禁止变更项 - 对外接口签名不得改变 - 业务逻辑行为不得改变 - 不允许顺手优化与本次无关的逻辑 执行要求 1. 先分析当前代码的职责输出结构拆解说明 2. 给出重构方案提取函数 / 拆分模块 / 优化数据流说明每个动作的理由 3. 实施重构 4. 运行相关测试 lint证明行为未变 附加要求重构完成后用不超过 5 句话总结核心改动便于 review。加了禁止变更项这几个字之后AI 的手明显老实了很多。它不会再自作主张地改掉一个看似多余却至关重要的 if 判断。4. 模板目录设计与团队复用把个人配置沉淀为项目资产模板这东西自己用着舒服不算完能沉淀下来给团队用、能跨项目复用才是真价值。我花了不少时间折腾目录组织方式目前的方案是可靠的也比较好理解。4.1 .claude 目录把模板放进项目本身Claude Code 支持项目级配置目录我个人的组织方式是这样的.claude/ ├── CLAUDE.md # 主模板根上下文也可放项目根目录 ├── commands/ # 斜杠命令文件 │ ├── review.md # /review 代码审查 │ ├── test.md # /test 写测试 │ ├── fix.md # /fix 修 bug │ ├── refactor.md # /refactor 重构 │ └── doc.md # /doc 生成文档 ├── templates/ # 提示词模板素材 │ ├── api-design.md # 接口设计模板 │ ├── db-migration.md # 数据库迁移模板 │ └── commit-message.md # 提交信息模板 └── memory/ # 项目经验沉淀可选 └── past-issues.md # 易踩的坑按模块记录每个斜杠命令文件本身就是一个 markdown开头写命令说明正文写提示词模板。执行/review时Claude Code 会读取这个文件并把内容作为提示词的一部分你只需要额外交代具体文件路径和改动背景。这个设计的妙处在于任务模板不进聊天记录不占上下文窗口用的时候才拉出来。比你把一大段模板直接粘贴到对话里干净得多。4.2 一套可直接抄的斜杠命令示例拿我常用的/review举例文件内容大致如下节选--- description: 按项目规范对代码进行系统性审查 --- 请以资深工程师的视角对以下代码进行审查。 代码路径{给出本次要审查的文件或 diff} 审查维度 1. 正确性边界条件、并发问题、异常路径 2. 安全性注入风险、敏感信息、越权 3. 性能N1 查询、循环嵌套、重复计算 4. 可维护性命名、拆分、注释 5. 测试覆盖核心分支是否有测试保护 输出要求 - 按 P0 / P1 / P2 三档标注问题严重度 - 每个问题给出具体位置与修改建议 - 最后给出 100 分制评分和一句总结用的时候只需要敲/review 代码路径src/api/order.ts 改动背景增加超时退款逻辑就行剩下的事情模板会自动完成。4.3 团队共享与版本管理模板沉淀下来之后我把它提交到 git 仓库里单独建了一个目录或者干脆用一个独立仓库管理叫claude-code-templates也行。团队其他成员 clone 下来在自己的项目里建个软链接或者直接复制到.claude/目录就能用。这里有个细节模板本身也会迭代所以模板仓库一定要做版本管理。我一般用 commit message 记录变更原因比如 fix: 审查模板增加安全维度客户反馈漏检了越权问题。这样后续谁能看到每次改动背后的动机也方便回溯旧版本。另外强烈建议在模板库里放一个README.md写清楚每个模板的适用场景和使用姿势。别指望队友自己看文件就能懂——我就吃过这个亏同事把 review 模板当普通文档读了根本没用起来。README 里可以用一句话说明 把 .claude 目录复制到你的项目根目录在 Claude Code 对话中输入 /review 即可发起代码审查首次使用记得确认当前分支为最新的开发分支。5. 实测中的教训模板太厚反而坏事迭代比一步到位更重要最后聊聊我在搭模板这件事上踩过的真正的坑。这些东西是文档里写不出来的也是我觉得对整个体系最有价值的部分。5.1 教训一CLAUDE.md 不是越长越好我第一次系统整理 CLAUDE.md 时犯过贪多求全的毛病把项目背景、架构演进、模块职责、注意事项、历史决策原因全写了进去洋洋洒洒两千多行。结果用起来反而不如以前好用——AI 的输出变得很平均重点不突出有些日常要执行的规范反而被淹没在长篇大论里。后来才明白Claude Code 读取上下文时重要性和长度存在权衡关键指令密度不能太低。一个两万字的项目文档拆成二十份塞给它效果反而不如两千字的高度提炼版。现在我的 CLAUDE.md 严格控制在 400 到 800 行只保留最核心、最频繁的信息。具体来说我在迭代中逐渐摸清了什么该留、什么该扔该留的技术栈、命令、目录约定、命名规范、完成定义。这些直接影响每次代码产出的质量和风格。该扔的历史改造记录、过时方案说明、尚在讨论中的计划。这些等需要时再说。该挪的与具体模块耦合度高的细节从根目录挪到子目录的 CLAUDE.md。5.2 教训二负面清单比正面规则更有力量我仔细比对过模板中应该做和禁止做两类指令的实际效果发现 AI 对负面指令的遵循度明显更高。这可能是因为大模型的训练数据里充斥着大量反例当你明确说不要用 antd时它检索到的相关性远超选择团队偏好的组件库这种模糊指引。所以我在模板里刻意留了不少负面约束- 禁止使用 any 类型无法避免时需要在单行加 eslint-disable 并写明理由 - 禁止在 service 层直接操作 req / res 对象 - 禁止在业务代码中使用 console.log统一走 logger - 禁止复制粘贴重复代码公共逻辑必须抽取 - 禁止修改 Prisma schema 后不生成 migration每一条背后都是真实踩过的坑。建议你也把自己项目里最常发生的几类AI 自作主张行为整理成负面清单塞进 CLAUDE.md。5.3 教训三模板要跟着项目一起演进模板不是一次性工程。我发现最有效的方式是——每次对 AI 的输出不满意先别急着改提示词先想想要不要更新模板。举个例子有段时间我发现 AI 写的 API 接口总是忘记做权限校验。在提示词里临时纠正了几次效果都不持久后来我把这条直接写进 CLAUDE.md 的完成定义里涉及写操作或敏感数据读取时必须包含权限校验逻辑。从那以后这个问题基本没有再犯。另一个典型的迭代节奏是当某个新指令连续触发两次以上就把它固化进模板当某条旧规则连续两周没用到就考虑删掉。我有意识地维护模板的增删记录保持它的精炼度。5.4 教训四低质量模板和高质量模板的差距在哪儿放一组实例对比可能更直观。假设你的项目是一个 Vue3 TypeScript 的中后台项目分别用两种模板让 AI 写一个弹窗组件。低质量模板的写法帮我写一个用户编辑弹窗包含姓名、手机号、邮箱三个字段保存时校验必填。AI 给出的东西你可能也猜到了模板是一个 v-if 加一个 div校验逻辑只有简单的非空判断样式没有对齐项目的设计系统组件没有拆分甚至可能没用 TypeScript。高质量模板的写法在 src/components/UserEditModal 下实现一个用户编辑弹窗组件。 功能要求 1. 基于 el-dialog 封装项目统一用 element-plus 2. 表单字段姓名必填最长20字、手机号必填正则校验、邮箱选填格式校验 3. 打开时自动回填用户数据关闭时重置表单校验状态 4. 提交时调 userApi.update成功后 emit(success) 并展示 ElMessage 提示 5. 样式参考现有 modal 组件宽度 480px 约束 - 使用script setup langtsprops 和 emit 都要定义类型 - 表单校验用 element-plus 的 rules不用手写 if 判断 - 提交中按钮 loading 状态后者看起来长了点但产出质量完全不是一个水平。这段需求描述里的信息密度和 CLAUDE.md 的规则是互补的——模板给全局约定提示词给具体任务细节两者配合才是完整的工程。5.5 团队推广的阻力与解法最后说一个团队协作层面的观察模板这事儿你自己用得再爽别人不跟进也是白搭。我遇到过的典型阻力是对语音和热情不足这不就是套个话术模板嘛我自己会写需求。我的解法是——在队友遇到明确问题时顺势推广而不是安利。今天他因为漏了分页参数被测试打了回来我就说你试一下 /api-list 这个模板它能提醒你补分页和排序参数。有了真实痛点模板的价值就看得见了比你发十篇博文到群里讲道理都有用。另一个更硬核的策略是直接走代码评审入口团队 PR 的模板里加一行AI 检查项已完成倒逼大家把模板用起来。当然这招要看团队的文化氛围技术型团队一般能接受管理型团队建议先温和试点。
阅读完成 · 觉得有帮助？
