1. 内容整体设计与思路拆解1.1 模板仓库到底解决什么问题先说背景。这段时间我一直在用 Claude Code 做日常开发辅助初期体验确实惊艳但用久了就发现一个尴尬问题每次新开一个项目它对我的偏好一无所知。明明上个项目已经反复强调过“测试文件用 Vitest 不用 Jest”“提交信息必须遵循 Conventional Commits”“碰到复杂问题时先给分析再给方案”换个项目文件夹它全都忘了又从零开始学我的脾气。后来我开始研究 claude-code-templates 这个方向才意识到问题的本质Claude Code 这类 AI 编程工具本身是一个“能力极强但缺乏稳定上下文”的执行器。它不像 IDE 那样有固定的配置意识它的行为完全由当前会话里的上下文决定。你给了足够多的背景它就表现得像团队里的老人你什么也不给它就表现得像一个聪明但不懂规矩的新人。模板仓库解决的就是这个上下文缺失问题。它把团队约定、编码规范、任务流程、偏好选择全部固化到一套可复用的文件体系里让 AI 在每次对话开始时就能自动加载这些约定。我用了一两个星期把模板体系搭起来之后明显感觉到生成代码的质量和稳定性有了质的提升——不是 AI 变聪明了是它终于“懂规矩”了。适合参考这套方案的读者我建议分为三类已经在用 Claude Code 但觉得每次对话都要重复交代的人团队里准备统一 AI 辅助编码规范、但不知道从哪下手的人对 AI 编程工具好奇、想了解如何通过配置提升效率的新手1.2 为什么用模板而不是每次口头约定有人可能会问我每次对话开头把要求写一遍不就行了为什么要单独搞一套模板体系我最初也是这么想的但实际用下来有三个问题第一是遗忘率问题。人类对话有上下文窗口限制如果你是在长会话中途才想起要补充规范前面生成的大量代码可能已经全部跑偏。比如你写了三个小时代码才想起说“错误处理统一用自定义异常”这个时候前面的代码基本都要返工。第二是完整性问题。口头约定往往是零散的、随机的。今天想到就说一条明天忘了就少一条。而模板仓库是系统化的整理能把团队规范完整沉淀下来并且跟随仓库版本迭代。第三是团队协作问题。如果模板是写在你自己脑壳里的换一个人来接手项目他又得从零开始摸索。但如果模板是仓库里的一个文件任何人 clone 下来就能获得相同的工作约定。用生活化类比来说这就像做饭。你自己做饭的时候凭手感加盐加糖味道全在脑子里但如果你要开一家餐厅就必须把每一道菜的配方和工序写成标准作业单。AI 编程模板就是那张标准作业单让 AI 这个“临时厨师”每次都能做出稳定的味道。2. 模板仓库的核心结构与文件解析2.1 一个可落地的模板仓库目录长什么样先说结论我最终搭出来的 claude-code-templates 目录结构是这样的不算复杂但每个文件都有明确的职责claude-code-templates/ ├── CLAUDE.md # 全局项目宪法角色、目标、核心约定 ├── agents/ │ ├── frontend-helper.md # 前端专项助手定义 │ ├── backend-helper.md # 后端专项助手定义 │ └── review-buddy.md # 代码评审专项助手定义 ├── skills/ │ ├── test-generation.md # 测试代码生成技能 │ ├── commit-message.md # 提交信息规范技能 │ └── refactor-assistant.md # 重构辅助技能 ├── commands/ │ ├── /review # 自定义斜杠命令执行一次代码评审 │ └── /explain # 自定义斜杠命令解释当前选中代码 └── examples/ ├── react-project.md # React 项目模板示例 └── python-service.md # Python 服务项目模板示例有人可能会想这不是跟某些提示词工程仓库长得差不多吗对的形式上确实类似但定位和深度有区别。Prompt 仓库往往追求的是“怎么把一个问题问得更清晰”而 claude-code-templates 追求的是“怎么把一套完整的工程规范注入到 AI 的执行体系里”。CLAUDE.md 是整个体系的入口文件。Claude Code 在启动时会自动读取项目根目录下的 CLAUDE.md把它作为基础上下文。所以这个文件不应该是各种要求的大杂烩而应该是整个体系的“宪法”——只放最高优先级、最通用的约定。2.2 CLAUDE.md 的内容组织原则我踩过最大的坑就是一开始把 CLAUDE.md 写成了百科全书塞了上千行。结果模型每次都把大量上下文用在加载这些要求上反而稀释了真正重要的约定而且因为内容太多AI 很容易顾此失彼。后来我总结了一套组织原则要像写律师事务所的客户指导意见一样——重点突出、层次分明、可操作。当前我的 CLAUDE.md 模板长这样这是精简版完整版会按项目细化# 项目说明 这是一个基于 React TypeScript NestJS 的全栈项目。 AI 的主要职责协助开发、代码审查、测试补齐、重构优化。 # 技术栈与命令 - 前端React 18、TypeScript 5、Vite、Tailwind CSS - 后端NestJS、Prisma、PostgreSQL - 测试Vitest、React Testing Library - 包管理pnpm - 运行pnpm dev、pnpm build、pnpm test # 编码规范 1. 组件优先使用函数组件 hooks禁止 class 组件 2. 错误处理统一使用自定义异常类禁止裸抛 Error 3. API 层统一封装 fetch 请求错误码以业务码为准 4. 文件命名组件用 PascalCase工具函数用 camelCase 5. 所有注释使用中文但代码标识符使用英文 # 任务处理流程 1. 收到任务先确认需求边界不确定的地方先提问 2. 涉及跨文件修改时先给出影响范围分析再动手 3. 所有新建文件必须包含基本错误处理 4. 完成代码后必须自查类型检查、lint、测试 5. 涉及第三方依赖新增时先说明理由再执行 # 禁止事项 - 禁止在不告知的情况下重命名文件 - 禁止删除测试代码来“简化”项目结构 - 禁止不经确认直接升级主要依赖版本注意看这里的内容结构不是让你告诉 AI“请你友善一些”“请你仔细一些”这种虚无缥缈的话而是给出可验证、可执行、具体的约束条件。AI 不擅长理解模糊指令但很擅长处理明确规则。2.3 agents、skills、commands 三个能力文件的区别这是 claude-code-templates 里比较关键的概念也是很多人容易混淆的地方。简单说agents 文件定义一个具有特定职责的“角色”有独立的 system prompt 和行为模式。比如“前端助手”会更关注组件结构和样式规范“代码评审助手”会更关注逻辑缺陷和安全问题。skills 文件定义一项可复用的“能力”解决特定类型的任务。比如“测试生成”技能里面会写清生成测试的步骤、断言规范、mock 策略。commands 文件定义一条可以直接触发的工作流通常通过斜杠命令执行。比如 /review 就是一键触发代码评审流程。拿我实际用的 agents/frontend-helper.md 来举例你是一名前端技术专家专注于 React 组件的开发与优化。 你的特长复杂组件拆分、hook 设计、性能优化、样式一致性。 工作原则 1. 组件拆分遵循“单一职责”一个组件只做一件事 2. 优先使用 React 官方推荐的模式避免过度封装 3. 状态管理优先使用 hooks context只有跨模块复杂状态才引入外部库 4. 样式使用 Tailwind 的原子类为主组件样式文件为辅 5. 每次修改后主动检查是否引入了不必要的 re-renderskills/test-generation.md 的核心内容是这样的思路任务为指定模块生成单元测试。 适用范围src/ 下的业务函数、组件、API 封装。 执行步骤 1. 分析目标代码的输入输出和依赖关系 2. 列出需要覆盖的核心场景正常路径、边界条件、异常分支 3. 使用 Vitest 编写测试使用 describe/it/expect 结构 4. 涉及网络请求时使用 mock 拦截避免真实请求 5. 测试命名使用中文描述行为例如 “当输入为空时返回默认值” 6. 完成后运行 pnpm test -- 目标文件 验证通过这套设计把“角色、能力、流程”三者解耦好处显而易见你可以只引入某个 agent 而不引入全部 skills也可以只给项目加载特定技能而不用改变整体角色。这样的组合灵活性是单纯写一大段 prompt 根本无法实现的。3. 实操过程从零搭建一套可复用的模板体系3.1 第一步明确你的使用场景和团队约定很多人一上来就开始写模板内容这其实是本末倒置。模板要写得好先得想清楚几个问题你的项目是什么类型前端后端全栈数据工程你的团队有没有已经存在的编码规范如果有一份文档直接把它拆解进去你希望 AI 扮演什么角色是“随时听命的执行者”还是“有主见的工程师”我的建议是先花半小时把这些问题的答案写下来做成一个草稿清单。这一步的质量直接决定了后续模板的实用性。我当时带着团队做这个事就是把大家一起约定的规范做成了一张表场景现有约定模板里怎么落地分支命名fix/: feature/: chore/ 前缀命令式规范写入 CLAUDE.md提交信息遵循 Conventional Commits沉淀为 skills/commit-message.md测试策略核心业务逻辑必须有单测沉淀为 skills/test-generation.md代码风格Prettier ESLint 强制直接写在 CLAUDE.md 编码规范里异常处理自定义异常类统一错误码写在 CLAUDE.md 禁止事项与规范里3.2 第二步编写 CLAUDE.md 核心指令按照我前面给的示例结构先把最高层级的配置写好。我个人的经验是CLAUDE.md 的篇幅控制在 80 到 150 行以内超过这个范围的要么拆到 agents 或 skills 里要么删掉一些不那么重要的规则。这里有一个很关键的小技巧把 CLAUDE.md 写完后先自己大声读一遍。读到哪条让你觉得“哦这个其实没必要写这么细”或者“这句太模糊了 AI 肯定不知道怎么执行”就改掉。模板不是论文每一句话都应该能直接映射到 AI 的一个具体行为上。比如不要写“请写出高质量的代码”要写“所有新增函数必须包含参数类型定义禁止使用 any”。前者是评价标准后者是可执行的规则。再贴一个我认为写得不错的 CLAUDE.md 片段注意它的“可验证性”## 环境信息 - Node.js 20 - pnpm 9 - 数据库本地 PostgreSQL连接信息见 .env ## 工作流约定 1. 用户描述需求后先输出实现方案等确认后再写代码 2. 写代码时先建文件骨架再填充实现细节 3. 每次改完代码后运行 pnpm typecheck 和 pnpm lint 4. 如果实现过程中发现需求矛盾立即停下来提问不要自作主张3.3 第三步沉淀可复用的技能文件CLAUDE.md 是“宪法”skills 则是“专项操作手册”。这一步我会重点讲怎么沉淀出真正好用的技能文件。以 commit-message 技能为例技能名称规范化提交信息生成器 触发条件用户要求生成 commit 信息或执行 git commit 处理流程 1. 运行 git diff --cached --stat 查看本次变更文件列表 2. 运行 git diff --cached 查看更多文件的具体变更内容 3. 根据变更内容判断主要类型feat、fix、refactor、docs、test、chore 4. 提交信息格式 type(scope): 中文摘要 空行 详细说明为什么做、效果是什么 5. 示例 feat(order): 新增订单取消功能 - 支持用户主动取消未支付订单 - 取消后自动释放库存 - 补充对应单元测试 6. 约束摘要不超过 50 字说明部分用条列式避免一段长文这里的关键是技能文件必须当成“标准作业程序”来写而不是让 AI 自由发挥。要明确触发条件、执行步骤、输出格式、约束条件。这和给新员工写工作手册的道理一模一样。类似的技能文件我至少沉淀了 8 个测试生成、提交信息、代码审查、重构辅助、接口文档生成、安全审查、依赖升级评估、数据库迁移脚本审查。每沉淀一个技能等于让团队多了一个随时可调用的“专家能力”。3.4 第四步接入工作流并持续迭代模板仓库写完之后不是扔在那里而是要嵌入日常工作流。我建议的做法是在项目的.claude/目录下建立与模板仓库的软链接或者直接拷贝关键文件这样 Claude Code 在启动时就会自动识别。如果你们团队用的是 monorepo可以在各级子项目里放独立的 CLAUDE.md实现“全局约定 局部定制”的叠加。具体如何接入可以参考这个流程项目根目录放全局 CLAUDE.md包含所有子项目通用规范每个子项目目录里放独立的 CLAUDE.md包含该项目的专属技术栈和命令通用技能文件集中在团队的模板仓库使用时按需拷贝到项目里模板仓库跟随实际使用反馈持续迭代每两周 review 一次我第一次搭完模板仓库后让团队里三个人同时开始用一周后收集反馈把三条不够清晰的描述做了修正原来说“代码质量要高”太模糊改成“所有公共函数必须覆盖核心分支的单元测试”原来没提架构约束导致 AI 经常把业务逻辑直接写在组件里加了“业务逻辑抽取到 service 层”原来测试技能里 mock 策略不明确补充了“只 mock 外部依赖内部函数之间不要 mock”这个迭代过程很重要。模板不是一次性产物它会随着项目和团队的成长越来越精细。4. 常见问题与排查技巧实录4.1 为什么模板写了但 AI 不遵守这是最常见的抱怨我也遇到过。分析下来主要原因有三个第一是优先级不明确。AI 在处理任务时如果指令之间有冲突它通常倾向于选择更具体的、更靠近任务上下文的指令。如果你的 CLAUDE.md 和当前对话里用户的需求冲突它通常会优先满足用户的即时指令。解决方案是把不可妥协的规则写进“禁止事项”并加粗或强调同时配合 agents 文件在角色层面强化。第二是模板内容相互冲突。比如 CLAUDE.md 说“统一使用 pnpm”skills 文件里却出现了“npm run test”的指令。这种冲突会让 AI 无所适从。我排查时会把所有模板文件检索一遍找出所有提到包管理器、命令工具的地方统一替换。第三是模板写成了规则而不是习惯。AI 不像人你告诉它“通常应该”它做不到必须告诉它“必须”和具体步骤。检查你的模板里是不是有太多“尽量”“一般来说”“可以考虑”之类的模糊词。如果有全部改成明确指令。4.2 模板过长导致上下文浪费和注意力稀释这个问题我前面提过值得展开细说。上下文窗口是有限的CLAUDE.md 加载后始终占据上下文预算。如果模板长度超过一定阈值会导致两个后果可用空间变少AI 能参考的代码和对话内容变少注意力被稀释模型对长文档中的每一条规则的遵守度都会下降我做过一个粗浅的对照实验分别用一个 50 行、200 行、500 行的模板去驱动同一个代码生成任务。模板规模生成代码质量对规范的遵守程度AI 响应速度50 行中较高快200 行高很高中500 行反而下降明显下降慢结论清晰不是模板越多越好存在一个“甜蜜点”。我的经验是单项目模板控制在 100 到 200 行之间把团队通用规范做成全局模板把项目专用内容独立出来。4.3 全局模板与项目模板冲突怎么办如果你同时有全局 CLAUDE.md 和项目级 CLAUDE.md很可能出现冲突。比如全局模板说“测试用 Jest”某个项目模板说“测试用 Vitest”AI 会怎么选实测下来的行为是项目级模板的优先级高于全局模板。Claude Code 对更靠近当前目录的配置有更强的偏好。所以解决方案是在全局模板里只放普适原则不涉及具体工具选型涉及技术栈和具体命令的内容一律放到项目模板里。同类问题也出现在 agents 和 skills 层面一个技能文件和一个角色定义对同一操作给了不同指示时优先以更具体、更贴近当前任务的为准。所以我在模板设计里会让 agents 文件描述“角色和风格”让 skills 文件描述“流程和步骤”从根上避免交叉冲突。4.4 如何验证模板是否真的生效很多人写完模板后心里没谱不知道 AI 到底有没有读到、读进去没有。我分享几个实测有效的验证方法直接发问法在对话里问“根据你的配置我们项目用什么包管理器错误处理机制是什么”如果它回答得准确说明模板已生效。命题作文法故意布置一个涉及多个规范的任务比如“实现一个用户登录接口”然后检查输出里是否包含了异常处理、参数校验、类型定义等约定要求。冲突测试法提出一个和模板规则冲突的请求比如“用 npm 装一下依赖”看它是否纠正你并遵循 pnpm 约定。如果直接照做了说明模板约束力不足。日志检查法Claude Code 的调试日志里可以看到它加载了哪些上下文文件确认 CLAUDE.md 被正确读取。这套方法我推荐团队里有专人负责维护模板的人定期跑一遍保证模板不是“写了就完了”。5. 进阶方向模板体系的更多扩展思路5.1 从单人项目走向团队资产当你把 claude-code-templates 用熟练之后值得花点时间把它从“个人配置”升级为“团队资产”。我的做法是在团队的 wiki 里建了一个专门页面把模板仓库的说明文档、使用方式、示例都整理出来。新成员加入时不再需要对着空气摸索“AI 怎么老不按套路出牌”跟着文档走十分钟就能搭好环境。更进一步可以把模板和 CI 结合起来。比如在 CI 流程里加一步“模板合规检查”自动检测当前仓库的 CLAUDE.md 是否过期、是否缺少必需的技能文件。这样每次代码提交都能保证模板体系处于最新状态。5.2 用模板沉淀团队知识库这是我觉得最有价值的一个扩展方向。传统知识库的痛点在于写了很多文档但真正需要的时候没人记得去查。而模板体系不同它把知识“注入”到了 AI 的执行上下文里。比如我们团队总结过一套“数据库迁移安全操作手册”以前是 wiki 里的一个页面真正做迁移时没人看。现在我把核心要点拆成 skills/db-migration.mdAI 在执行数据库迁移相关任务时会自动带上这些约束相当于每个开发者身边都多了一个“懂规矩的迁移助手”。这个思路可以复制到很多场景代码审查清单、发布上线检查项、安全审计规则、性能优化惯用法。凡是反复用得到、又容易被遗忘的经验都值得沉淀成模板的一部分。5.3 多场景模板的编排最后聊一下模板的“编排”。当你拥有十几个 agents、skills、commands 之后怎么组合它们也是一门学问。我们目前的做法是按场景分了三套预设日常开发模式加载基础 CLAUDE.md frontend/backend helper代码审查模式加载 review-buddy agent review command重构优化模式加载 refactor-assistant skill 专属 CLAUDE.md 片段这三种模式可以在 branches 或目录级别做区分也可以做成项目里不同文件夹下的独立 CLAUDE.md。用到哪个场景就激活哪套配置避免一次性把所有能力都塞进上下文。我在实际使用中发现最稳定、效率最高的使用方式不是让 AI 同时在十个角色里切换而是“一个任务一个清晰的身份”。模板编排本质上就是在给 AI 分配合理的工作焦点这比一味地堆砌能力要重要得多。