我把Claude Code用成了一套可复用的模板工程先说明一点claude-code-templates不是某个官方发布的插件而是我把 Claude Code 在实际项目里跑顺之后沉淀出来的一套工程化模板思路。简单说就是把你平时反复给 AI 交代的背景、约束、流程、命令固化成文件放进项目仓库让 Claude Code 每次进入项目时自动加载这些上下文。这套东西解决的核心问题是同样的项目背景为什么每次开新会话都要重新讲一遍为什么有时候 AI 生成的代码风格前后不一致为什么团队里两个人用同一个工具产出的质量差别巨大答案不在于模型本身而在于你有没有给它一份稳定的“工作手册”。适合谁来参考如果你在用 Claude Code 写代码、做重构、写测试或者你想让团队里所有人都能用同一个 AI 工作流这套模板思路可以直接抄作业。下面我把完整的设计逻辑、目录结构、每个文件的写法、以及我踩过的坑全部拆开讲。1. 模板工程解决的不只是重复劳动1.1 从“对话式编程”到“工程化编程”大多数人用 Claude Code 的方式是对话式的打开终端输入claude然后开始描述需求。这种方式在小任务上没问题比如“把这个函数改成异步”但一旦项目稍微复杂一点问题就来了。你需要在每次会话里花十几分钟重新描述项目背景告诉它技术栈是什么、目录结构怎么组织的、代码风格偏好是什么。更糟糕的是如果会话中断重新打开后它完全失忆你又得从头来一遍。这就像每次请同一个外包工程师来帮你改代码但他每次进门都忘记你项目是干什么的你得重新讲解半小时。模板工程化改变的是这个模式把上下文从“对话中”转移到“文件里”。Claude Code 原生支持项目级配置文件比如CLAUDE.md它会在每次会话启动时自动读取。我们把项目的所有关键信息写进这类文件AI 一进场就自带“记忆”直接进入工作状态。这省下的不只是时间更是让 AI 输出的稳定性产生了质的飞跃。1.2 什么样的项目需要模板不是所有项目都需要一套完整模板。我的判断标准很简单这个项目是否需要被 AI 反复操作并且操作结果需要保持一致性如果只是临时写个脚本一次性用完就删那确实不需要。但只要是下面几种场景模板的投入产出比非常高长期维护的业务项目AI 需要频繁理解和修改业务逻辑背景信息不重复讲。多人协作的仓库团队里每个人都用 Claude Code但大家给 AI 的指令习惯完全不同产物风格五花八门。模板是统一标准的最省力方式。需要高度复用的脚手架/起点比如你经常要开新项目每次都要配置同样的代码规范、目录结构、CI/CD 流程把这些制成模板新项目三分钟初始化完。包含复杂流程的任务比如发布流程、数据库迁移流程、代码评审流程。这些流程步骤多、约束多让 AI 按模板执行比口头交代可靠得多。换句话说模板是把 AI 从一个“聪明但健忘的临时工”变成“懂规矩有记忆的固定成员”。2. 目录结构与模板文件设计2.1 我推荐的最小目录骨架先看一个我实际在用的目录结构这是精简过的版本适合大多数中大型项目your-project/ ├── .claude/ │ ├── CLAUDE.md # 项目主上下文Claude Code 自动加载 │ ├── commands/ │ │ ├── review.md # 自定义斜杠命令代码评审 │ │ ├── test.md # 自定义斜杠命令运行测试 │ │ └── commit.md # 自定义斜杠命令生成规范提交信息 │ └── agents/ │ ├── frontend.md # 前端专项子代理 │ ├── backend.md # 后端专项子代理 │ └── debugger.md # 调试专项子代理 ├── docs/ │ └── ai/ │ └── coding-standards.md # 被 CLAUDE.md 引用的详细规范文件 ├── templates/ │ ├── feature.md # 新功能开发的流程模板 │ ├── bugfix.md # Bug 修复流程模板 │ └── refactor.md # 重构流程模板 └── .claudeignore # 类似 .gitignore控制 AI 不可读文件这套结构不是凭空拍脑袋定的它沿着 Claude Code 的加载机制设计CLAUDE.md是入口commands/定义快捷指令agents/定义不同角色的子代理templates/是更细粒度的执行脚本。2.2 为什么入口文件必须叫 CLAUDE.mdClaude Code 约定俗成的加载机制是启动时自动读取项目根目录下.claude/CLAUDE.md旧版本也可能读根目录CLAUDE.md新版本推荐放在.claude/内。这个文件就是 AI 的“入职培训手册”。它不需要写很多但必须把关键信息放在最前面因为大模型的注意力机制决定了它会比较关注文件开头的内容。我的经验是主文件控制在 200 行以内放最核心的约束详细的规范放到单独文件里用相对路径引用。原因是上下文窗口始终是有限的如果CLAUDE.md太长它会稀释真正重要的指令反而降低输出质量。类似写文档时把摘要放在前面详细内容放附录一样。2.3 每个文件该装什么内容给每个核心文件定位清楚避免它们职责重叠CLAUDE.md项目的一句话简介、技术栈、目录地图、全局规范引用、常用命令入口、禁忌列表。commands/*.md每个文件对应一个斜杠命令例如输入/review就触发代码评审流程。文件内写好这个命令的完整执行步骤和输出要求。agents/*.md定义子代理的角色、职责边界、可用工具、禁止做的事。用claude --agent 名字或全局配置按需调用。templates/*.md用于更复杂的任务流程比如“新功能开发”包含需求澄清、方案设计、编码、测试、提交信息生成等阶段每一步都有明确交付物。.claudeignore防止 AI 读取敏感文件或无关文件比如.env.local、大型二进制资源、构建产物目录。这样设计的好处是每一层只解决一个问题。主文件负责建立全局认知命令层负责快速触发agent 层负责专业分工模板层负责复杂流程的标准化。层与层之间靠路径引用串联不会出现一块巨大的文件既讲背景又讲操作流程的情况。3. 关键文件的编写要点与实操示例3.1 CLAUDE.md写好项目背景但不写小说写CLAUDE.md最容易犯的错是把它当成项目说明书事无巨细全部往里塞。我自己写过一版 500 行的结果 AI 反而变得迟钝连简单的指令都要犹豫半天。后来我把行数砍到 180 行效果明显变好。核心结构我建议这样# 项目名称 一句话描述项目是做什么的目标用户是谁。 # 技术栈 - 前端React 18 TypeScript Vite - 后端Node.js 22 Fastify - 数据库PostgreSQL 16 Prisma ORM - 部署Docker GitHub Actions # 目录结构速览 - src/components —— UI 组件原子组件优先 - src/services —— API 调用层 - src/utils —— 纯函数工具库 - prisma/schema.prisma —— 数据模型定义 # 代码规范 严格遵循 Code Standards见 docs/ai/coding-standards.md。 重点强调 1. 组件使用函数式写法禁止 class 组件。 2. API 层错误需要统一封装为 ApiError。 3. 所有文件名使用 kebab-case组件名使用 PascalCase。 # 常用命令 /test —— 运行测试并修复失败项 /review —— 代码评审输出问题清单 /commit —— 生成符合 Conventional Commits 的提交信息 # 禁区 - 禁止修改数据库结构而不先询问确认。 - 禁止在非必要情况下引入新的依赖库。 - 禁止改动 src/services 下的 API 路径格式。每一条信息都应该具备“约束力”或者说能被 AI 直接执行而不是模糊的“要写高质量代码”这类空话。比如“禁止在非必要情况下引入新依赖”和“要写简洁代码”相比前者可执行性高得多。3.2 commands 目录把重复操作变成斜杠命令自定义命令是提升效率最快的功能。以前我让 AI 做一次代码评审要在对话框里写一大段“请检查当前分支改动输出问题清单并按严重程度排序重点关注潜在 bug 和安全问题……”而现在输入/review即可。它的文件格式并不复杂。看一个实际的review.md--- description: 对当前分支进行一次代码评审输出问题清单 argument-hint: 可选指定评审范围例如 src/components allowed-tools: Read, Grep, Glob, Bash --- # 代码评审流程 你是一名资深代码评审专家请严格按以下步骤执行不要遗漏。 ## 步骤 1. 使用 git diff main...HEAD 获取当前分支的变更内容。 2. 如果用户指定了评审范围参数仅评审该范围内的变更忽略其他文件。 3. 逐文件阅读上下文不能仅凭 diff 局限判断。 4. 输出评审结果严格按如下格式 ## 评审结果 ### 严重问题必须修复 - 文件路径 行号 问题描述 修复建议 ### 建议改进可选 - 文件路径 行号 问题描述 ### 优点 - 列出值得保持的写法方便团队推广 ## 评审原则 - 只基于现有代码事实不猜测代码之外的需求。 - 不修改代码只输出评审意见。 - 如果 diff 过大优先关注逻辑变更和新增代码。 - 所有建议必须具体禁止“提升代码质量”这类空话。编写自定义命令的核心是给出的命令要以结果为导向流程必须可执行、可验证。上面对 breadcrumb 的格式有明确要求AI 输出时就容易对齐如果只写“请评审代码”它可能给你一份泛泛的评论价值不高。3.3 agents 子代理让专业的人干专业的事Claude Code 的子代理Agent机制允许你定义不同的角色每个角色有自己的背景知识、工具集和行为边界。这特别适合中大型项目因为让同一个 AI 既写前端又写后端还要管数据库迁移它很容易在各种约束之间摇摆。我举一个 backend agent 的写法# Backend Agent 角色定位 你是这个项目的后端服务开发专家熟悉 Fastify、Prisma、PostgreSQL。 你的职责范围包括API 开发、数据模型变更、业务逻辑实现、单元测试编写。 工作规范 1. 所有数据库 schema 变更必须经过确认禁止直接执行迁移。 2. API 响应统一使用 { data: T } 包裹错误使用 { error: { code, message } } 格式。 3. 新增接口必须同步编写 fastify 路由测试测试文件放在 __tests__/routes/ 下。 4. 所有查询必须使用参数化查询禁止拼接 SQL 字符串。 5. 修改已有接口时注意兼容旧客户端必要时显式声明破坏性变更。 边界 - 不负责前端组件逻辑如果发现涉及前端改动在输出中说明并跳过。 - 不负责部署运维遇到部署问题直接标记为“需要人工介入”。 - 不修改与后端无关的配置文件如 GitHub Actions 工作流。 可调用工具 Read | Grep | Glob | Bash | Write | Edit在主上下文里可以通过/agent backend的格式切换到这个角色也可以直接在对话中让 AI 根据任务类型选择对应 agent。这个方法对大型仓库效果尤其明显因为子代理启动时会带着自己的专属上下文不会把其他模块的信息混进来判断更聚焦。4. 实操从零搭建一套可用模板4.1 初始化流程按这个顺序来比较稳很多人上手模板时很兴奋一上来就写一大堆规范文件结果发现 AI 根本不遵守或者互相矛盾。按我多次试错的经验推荐的初始化顺序是第一步先盘点项目最痛的重复劳动。问自己三个问题我每次让 AI 重复交代得最多的是什么AI 最容易在哪些地方犯错团队里大家的操作习惯差异在哪里把答案列成一个清单这就是模板要覆盖的内容。第二步从 CLAUDE.md 开始只写三块。项目简介、技术栈、目录结构。不要上来就写规范。先跑通加载机制确认 AI 真的“记住”了背景。在对话里问它“我们的技术栈是什么”如果答对了再进入下一步。第三步补充“禁区”条目。哪些事情你绝不允许 AI 擅自做例如“不要未经确认就执行prisma migrate reset”、“不要修改测试数据”、“不要升级 package.json 中的依赖版本”。这些约束越早加入越好因为 AI 一旦形成某种行为习惯后面纠正的成本会变高。第四步添加第一条自定义命令。选你日常频率最高的操作比如“生成提交信息”或者“写单元测试”。先写一版试用一周根据实际输出效果迭代优化。这比一次性写十个命令然后发现都不好用要强得多。第五步引入 agent 和流程模板。当主文件和命令都稳定之后再根据项目复杂度决定是否需要拆分 agent。小项目一个 agent 就够大项目再按前后端拆分。流程模板如 feature.md属于进阶玩法它适合任务链路长、交付文档多的场景。4.2 第一次运行如何验证模板有没有生效模板文件写好之后先不要急着干活花 5 分钟验证它的加载状态。在项目根目录启动claude直接问几个封闭式问题我们的技术栈是什么请列出前端的 UI 组件目录在哪里。如果答案和CLAUDE.md里写的完全一致说明加载成功。如果不一致先检查文件路径新版 Claude Code 要求放在.claude/CLAUDE.md如果你还放在根目录下的CLAUDE.md可能不会被加载或者只作为 fallback。我遇到过路径搞错导致配置一直不生效的情况排查了半小时最后发现是目录拼写多了个.claude嵌套。再测自定义命令输入/review看 AI 是否按你定义的流程走。如果它完全不理会你的流程直接给了另一套输出大概率是命令文件的 frontmatter 格式有问题可以参考官方文档里的description字段写法注意 YAML 语法不能出错缩进错了整个文件都会被忽略。4.3 模板的版本管理像管代码一样管提示词模板文件本质上是代码的一部分所以必须纳入版本管理。我的实践是把.claude/和templates/直接放进 Git 仓库每次修改都走正常的 PR 流程。但这里有一个坑直接改模板文件会影响所有正在使用它的人。比如你调整了命令格式团队其他人下周用/commit时生成的信息格式可能和他们上次不一样。所以我的建议是模板修改遵循“先加后改”的原则。新增参数或新约束时先保留旧的做兼容至少维护一个版本周期再移除废弃内容。另一个建议是给模板文件加一行版本注释# template-version: 2.3.0这样当 AI 的输出行为变得不可解释时可以快速回到上一个版本检查是否是模板变动引起的。我在一个团队里用这个方法排查过一次诡异问题——某个 agent 突然拒绝执行测试命令结果发现是模板里新增的一条工具限制把 Bash 工具禁用了。5. 常见问题排查与避坑实录5.1 模板不生效或行为异常优先查这三处第一个排查点是文件路径和权限。.claude目录必须位于项目根目录而且当你在子目录里启动claude时它向上查找的路径可能和你预期不同。如果你经常在src/components/这样的子目录里工作建议在CLAUDE.md里加一句“无论当前工作目录在哪里始终以项目根目录为基准进行代码操作”。第二个排查点是上下文被其他内容稀释了。Claude Code 会自动把项目里的某些信息附加到上下文中比如 git 状态、当前打开的文件等。如果项目里有大量无关文件AI 的注意力会被分散。这时候.claudeignore就有用了。我一般在里面写上node_modules/ dist/ build/ coverage/ *.lock .env*第三个排查点是模板内部逻辑冲突。比如你在CLAUDE.md里写“所有 API 返回格式统一”但在某个 agent 文件里又写了“GraphQL 接口按 schema 返回原始结构”AI 检测到冲突时会选择其中一条执行而这条往往是更具体的文件里的规则容易造成主规范失效。解决方法是定期审查各层模板之间是否互相矛盾。5.2 上下文过载模板不是写得越多越好我在前面反复提到行数控制这里用一个真实对比说明。去年我在一个项目里“精益求精”写出了超过 1500 行的全套模板包括详细的编码规范、数据库设计原则、UI 组件验收标准、甚至还有专门的 prompt 来提高测试覆盖率。结果是什么呢AI 的执行速度变慢了而且开始出现“顾此失彼”的情况。比如它会严格遵守代码风格规范却忘了更重要的安全约束。原因是上下文太长模型需要在大量信息中寻找与当前任务相关的部分这个过程本身就容易出错。我的建议是分级加载CLAUDE.md只保留 20% 的高频关键信息剩下 80% 的细节放到子文件里。让 AI 在需要时主动读取相关文件而不是一开始就把所有内容灌进上下文。举个例子业务流程文档放在docs/business/order-flow.md然后在CLAUDE.md里写“涉及订单流程时先阅读 docs/business/order-flow.md 再回答问题”。5.3 团队协作时模板如何避免“互相打架”团队场景下的模板管理和单人使用完全是两码事。最常见的问题是A 成员在前端项目里加了一条命令B 成员在另一个分支也加了同名命令合并时冲突。还有一些人会在自己的本地覆盖仓库里的模板文件导致同一个项目在不同人电脑上表现不一致。我用的方式是两层结构仓库内模板和本地个人模板分开。仓库内.claude/是团队共识只允许通过 PR 修改本地用户级配置放在~/.claude/个人的快捷习惯放在那里。这样团队共识变成基线个人偏好作为增量互不覆盖。执行优先级上项目级模板优先于用户级模板这个顺序千万别搞反否则本地配置会压制团队的规范。还有一个容易被忽略的细节模板里不要写个人昵称或针对特定人的暗语。我见过一个团队在CLAUDE.md里写了“如果遇到数据库问题问一下老张”结果 AI 每次都会认真地建议“请联系老张”而老张已经离职三个月了。模板面向的是所有人信息必须中性化、客观化。5.4 一个速查表常见现象与对应解法现象可能原因解决方向完全无视 CLAUDE.md 中的规则文件路径错误或权限不足检查.claude/CLAUDE.md是否在根目录只遵守部分规则模板内部冲突或信息过载精简主文件把细节移到子文件命令不生效输入/xxx没反应命令文件 YAML frontmatter 格式错误检查description字段和缩进输出风格不一致缺少明确的风格约束在模板里给出正反示例读取了不该读的敏感文件未配置.claudeignore排除.env*等敏感路径在不同子目录启动时表现不一致AI 对路径理解混乱在模板里写死“以项目根目录为基准”变更了数据库却不询问缺少“禁区”条目在CLAUDE.md中明确禁止项这张表是我实际排查过程中的记录不一定覆盖所有场景但能帮你快速定位大部分高频问题。6. 模板只是起点下一步可以这样演进6.1 从模板到工作流把复杂任务拆成阶段模板的下一步是把它升级成完整的工作流。以新功能开发为例feature.md可以定义五个阶段需求理解、技术方案、编码实现、自测验证、提交合并。每个阶段有独立的验收条件AI 不能跳步。这个想法来自我的一次惨痛经历早期我让 AI 直接实现一个新功能它非常高效地写了一堆代码但需求理解错了结果全部返工。后来我在模板里加了“需求澄清”阶段强制 AI 在动代码之前先复述需求并提问把模糊地带在动手前解决掉。这一步多花三分钟至少省下三小时。6.2 模板的复用跨项目复制与定制最后分享一个跨项目复用的方法。我维护了一个私人的template-starter仓库里面放的是通用模板目录。每开一个新项目第一步不是npm init而是把模板目录复制到项目里再根据技术栈做减法。比如新项目用的是 Vue 而不是 React那就把 CLAUDE.md 里的技术栈替换掉前端 agent 的描述也改成 Vue 版。保留的是那些跨项目通用的部分代码评审流程、提交信息规范、测试约束等。这就像搬家时把厨具和书籍打包带走新家只需添置少量家具。我验了一段时间后从零到完成一个可运行的新项目初始化包括模板适配大概只需要 20 分钟而这 20 分钟换来的是之后每次 AI 交互都像和老同事配合一样顺畅。这个模板工程我不会停止迭代因为 AI 的能力在变项目复杂度在变模板本身也必须跟着演进。它不是写一次就一劳永逸的静态文件而是一个需要持续维护的活文档。我的建议是每个月抽半小时审视一遍哪些规则已经过时哪些约束可以移除哪些流程因为 AI 能力增强而可以简化。这套机制的价值用一句话总结就是先让 AI 懂规矩再让它放开手脚干活。