1. 模板库整体设计思路
我一直有个观点：Claude Code 这类终端里的 AI 编程工具，能力上限从来不取决于模型本身，而是取决于你怎么跟它对话。模型参数摆在那里，能爆发多少实力，全靠提示词和上下文组织。而“模板”这件事，就是把那些零散的好用提示词、项目规范、代码风格约束，沉淀成一套可以复用、可以迭代、可以分发给团队的东西。claude-code-templates 这个项目，干的就是这件事。
先说这个项目能解决什么问题。很多人用 Claude Code 的第一感受是：让它写个函数挺好使，但让它改一个跨多个文件的复杂需求，它就容易“失忆”——忘了项目结构、忘了代码风格、忘了你之前强调的约束。原因很简单，终端会话的上下文窗口是有限的，如果每次都在对话里重复交代项目背景，既浪费 token 又容易遗漏。模板化之后，把项目的背景说明、技术栈、目录结构、编码规范全部固化到CLAUDE.md文件里，Claude Code 每次启动都会自动加载，这就相当于给 AI 配了一个“项目入职手册”。它不再需要你反复解释，从第一次对话开始就知道自己在跟什么样的代码库打交道。
整个模板库的设计遵循一个分层思路：最底下是基础系统提示词，类似“你是资深全栈工程师，代码要简洁、注释要精简”；中间层是项目级CLAUDE.md，描述具体项目的技术栈、目录结构、构建命令；最上层才是具体的任务模板，比如“帮我写一个带分页的列表接口”“把这个组件从 class 改成 hooks”。这三层各司其职，底层管行为风格，中间层管项目认知，顶层管任务执行。从实践来看，这套分层越清晰，AI 的输出就越稳定。
项目适合谁来用，我简单划分一下：如果你只是偶尔让 Claude Code 写个脚本，模板化对你来说意义不大；但如果你把它当成日常主力工具，每天要处理多个仓库的增删改查，或者你带的小团队要用 Claude Code 协作，那模板库的收益就非常明显。尤其是多人协作场景，统一模板等于统一了 AI 的行为基线，不同人问同样的问题，得到的代码风格不会差太远。这一点对代码 review 来说太重要了。
2. CLAUDE.md 配置拆解与写法
2.1 CLAUDE.md 在模板库中的核心地位
CLAUDE.md 是 Claude Code 项目级记忆的载体，相当于它的“长期记忆”文件。放在项目根目录下，每次运行都会自动被读取，省去了你反复交代背景的麻烦。我见过不少人在模板库项目里维护了多个 CLAUDE.md 版本，分别对应不同规模的项目：小型脚本项目只写两三行核心约束，中大型项目则写清楚技术栈、目录结构、测试命令和代码风格要求。
写法上有几个关键点。第一，文件位置要固定，就放项目根目录，不要嵌套到子目录里，否则 Claude Code 默认不会读取。第二，内容要精炼但信息密度高，不要写废话，比如“这是一个电商项目”这种就没用，要写“本项目使用 Next.js 14 App Router，服务端组件优先，所有 API 路由放到 app/api 目录下，使用 zod 做入参校验”。第三，语气要直接，Claude Code 对祈使句的响应要好过描述句，直接写“不要使用 any 类型”比“建议尽量避免使用 any”管用得多。
我实际操作中会刻意在里面加一段“项目陷阱说明”，专门记录那些容易踩坑的地方。比如某个模块历史包袱重、改动极易引入回归，或者某个接口有特殊的鉴权逻辑，如果 AI 不知道这些，很容易写出表面正确、实际跑不通的代码。把这些写进 CLAUDE.md，相当于把项目的隐性知识显性化了。
注意：CLAUDE.md 不是越写越长越好。超过 100 行的 CLAUDE.md 反而会稀释重点，让 Claude Code 抓不住真正重要的约束。我的经验是控制在 50~80 行，只保留“不知道就会写错”的信息。
2.2 一个合理 CLAUDE.md 的内容骨架
如果你从零开始写，我建议按下面这个结构填充：
# 项目概述 - 项目定位：一句话说清楚这是做什么的 - 技术栈：框架、语言版本、关键依赖 - 运行环境要求：Node 版本、包管理器版本 # 目录结构 - 核心目录的职责说明 - 新增代码应该放在哪里 - 哪些目录不允许随意改动 # 编码规范 - 语言特性使用约束（如 TypeScript 严格模式） - 命名规则（文件命名、变量命名、组件命名） - 样式方案（Tailwind / CSS Modules / styled-components） # 命令 - 安装依赖：xxx - 启动开发：xxx - 运行测试：xxx - 构建生产：xxx # 项目陷阱 - 已知的坑和注意事项 - 历史包袱说明这六个板块是我多次迭代后留下来的，每一个都有明确的存在理由。“项目概述”让 AI 建立基本认知；“目录结构”解决“代码该往哪放”的问题，这是 AI 写代码最容易出错的地方，它总是倾向于把所有逻辑堆在一个文件里；“编码规范”保证代码风格统一；“命令”板块让 AI 能自己跑测试和构建；“项目陷阱”则是经验沉淀，越攒越值钱。
2.3 CLAUDE.md 的维护节奏
模板库里的 CLAUDE.md 不是写一次就完事的，要跟着项目演进持续维护。我自己的节奏是：每次项目有大变动（比如引入新依赖、迁移目录结构、切换包管理器）就顺手更新，每次发现 Claude Code 反复犯同一个错误，就把它写进陷阱区。本质上，CLAUDE.md 就是一个项目给 AI 使用的 README，你自己希望新同事入职时知道什么，就写给 AI 看什么。
3. 核心模板设计详解
3.1 系统提示词模板的设计要点
系统提示词是最底层的模板，它的作用是定义 AI 的角色和行为边界。在这个模板库项目里，系统提示词模板通常包含角色定义、能力边界、输出风格和通用约束四部分。我常用的一个模板长这样：
你是一名资深全栈工程师，熟悉 TypeScript、Node.js、React 和现代前端工程化实践。 你在回答编程问题时遵循以下原则： 1. 优先考虑代码的可读性和可维护性，而不是炫技。 2. 在给出代码前，先简单说明你的实现思路。 3. 代码需要包含必要的类型定义，禁止使用 any。 4. 对于复杂逻辑，每行关键代码需要附带简短注释。 5. 如果需求中有歧义，先提出假设再给出实现。 6. 不要生成无关的代码或过度的抽象。这里有个容易被忽略的细节：能力边界要写清楚。你不告诉 AI 它能做什么，它就会默认什么都能做。但实际项目里，你可能希望它只管某个模块，或者不希望它擅自改动某些文件。把边界写进去，能省掉很多“它干了我没让它干的事”的麻烦。
输出风格这部分可以根据个人喜好调整。有些人喜欢直接给代码不要废话，有些人希望 AI 先讲思路再写代码。这个没有标准答案，但是建议写明确，因为 Claude Code 在“简洁解释”和“详细解释”之间的差别很大，你不写它就默认按中间态输出，这个中间态往往不是我们最想要的。
3.2 代码生成模板：让 AI 按套路出牌
代码生成模板是使用频率最高的模板类型，它的核心价值是把 AI 的输出规范到特定格式，减少你手动清理和调格式的时间。拿一个新增 API 接口的模板举例：
根据以下需求生成 API 接口代码： - 接口功能：{在这里描述接口功能} - 路由路径：{在这里指定路由} - 入参说明：{在这里描述入参字段及校验规则} - 出参说明：{在这里描述响应结构} 生成代码时需要遵循： 1. 使用 zod 做入参校验，错误统一抛出 HttpException 2. 响应用统一的 ResponseWrapper 包装 3. 数据库操作使用 Prisma，所有查询必须包含错误处理 4. 接口文件放在 src/modules/{moduleName}/ 目录下 5. 生成完成后，给出接口测试用例这个模板的精髓在于占位符 + 约束条件的组合。占位符让你每次只需要填“本次需求的具体内容”，约束条件保证填完之后，产出物的格式和风格是固定的。使用一段时间后你会发现，AI 生成的代码几乎不需要修改就能合入，因为它已经内置了你团队的所有约定。
我还见过有人在模板库里维护“重构类模板”“测试类模板”“Bug 修复类模板”，思路都差不多，就是提前定义好 AI 遇到这类任务时的处理流程和输出规范。
3.3 工作流模板：把多步操作变成一步
工作流模板解决的是“一系列操作”的问题，而不是单个代码生成问题。举个例子，假设你每次提交代码前都要做这些事：跑 lint、跑测试、检查类型错误、更新 changelog。你可以把这个流程写成一个模板：
你是一个代码审查助手。在执行以下流程之前，请先读取当前分支的 git diff。 1. 检查是否有 TypeScript 类型错误，如有请指出具体文件和行号 2. 检查是否存在未使用的变量或 import 3. 检查代码风格是否符合项目的 ESLint 规则 4. 检查是否有明显的逻辑漏洞或边界条件未处理 5. 输出审查报告，按严重程度排序，并给出修改建议 6. 等待用户确认后，再执行修改工作流模板和普通提示词最大的区别是：它定义了先后顺序和暂停点。上面的例子里第 6 步“等待用户确认”就是一个暂停点，有了它，AI 不会一股脑把代码全改完，而是先把问题列给你看，你决定改哪些它才改。这种控制感在日常使用中非常重要，否则 AI 容易“过度热情”地乱改一气。
3.4 模板变量体系的组织方式
模板库里大量模板都包含占位符，这就得有一套统一的变量命名规则，否则不同模板之间风格不统一，用起来会很别扭。我目前的习惯是：用户输入的内容用花括号包裹，比如{功能描述}、{模块名}，系统自动生成的内容用尖括号包裹，比如<当前日期>、<git分支名>。这样一来，一眼就能看出来哪些是你需要填的，哪些是自动替换的。
另外，模板之间也要有引用关系。比如“代码生成模板”里引用了“系统提示词模板”的基本约束，那系统提示词模板一变，所有引用它的模板自然生效。这个引用关系在模板库里用文件命名来体现，比如base-system-prompt.md被api-creation-template.md引用。一开始你可能觉得这种层级麻烦，但模板积累到几十个之后，这种组织方式能让你少维护很多重复内容。
4. 实操过程与关键步骤记录
4.1 从零搭建模板库的完整步骤
我自己搭建模板库的过程，可以拆成下面几个步骤，照着做基本不会走弯路：
第一步：确定目录结构。建议按用途分类，而不是按项目分类。你可以参考下面这个结构：
claude-code-templates/ ├── system-prompts/ # 系统提示词模板 ├── project-guidelines/ # CLAUDE.md 模板 ├── task-templates/ # 任务级代码生成模板 ├── workflow-templates/ # 工作流模板 ├── scripts/ # 辅助脚本 └── README.md按用途分类的好处是模板之间可以互相引用，而按项目分类会导致同一个模板在不同项目里各存一份，改一处还得去另一处同步，维护成本翻倍。
第二步：先写三个高价值模板。不要一上来就追求数量，先写一个系统提示词模板、一个 CLAUDE.md 骨架、一个最常见的代码生成模板，放进库里试用。用一周左右，你会明显感受到哪些地方不好用、哪些约束没生效、哪些内容是多余的。这一周的反馈比任何理论推演都管用。
第三步：沉淀项目级配置。把你日常项目里好用的 CLAUDE.md 内容提炼出来，去项目化，保留通用部分，生成一个新的模板。比如“电商项目”变成“标准业务系统”，“订单模块”变成“业务模块”。这个过程是从“给自己用”到“给别人用”的转化，也是模板库真正成型的关键一步。
第四步：写 README 说明每个模板的适用场景。这一步很多人会省略，但实际用下来很重要。模板库规模超过 20 个文件后，连你自己都会忘了某个模板具体是干嘛的、跟另一个模板有什么区别。README 里写清楚“这个模板解决什么问题、什么时候用、怎么用”，能大幅降低使用成本。
4.2 让模板库自动生效的配置技巧
CLAUDE.md 模板做到后面，你会发现不同项目需要不同的 CLAUDE.md 内容。手动复制粘贴显然太低效，我这边有两个自动化思路，你可以参考。
第一个思路是写一个 Shell 脚本来做“模板安装”。比如这个install.sh：
#!/bin/bash # 用法：./install.sh system-prompt standard # 作用：将指定模板复制为当前项目的 CLAUDE.md TEMPLATE_DIR="$(dirname "$0")/project-guidelines" cp "${TEMPLATE_DIR}/${1:-standard}.md" ./CLAUDE.md echo "已安装项目配置模板：${1:-standard}.md"这个脚本解决的问题是：项目里已有 CLAUDE.md 时，你想换一套配置，不用手动去备份、删除、粘贴，一条命令搞定。脚本虽小，但每天省下的操作次数多了，体感差异还是很明显的。
第二个思路是把模板库做成 Git 子模块，在项目仓库里引用。这样模板库更新了，项目里执行git submodule update就能拿到最新版本。对团队协作来说，这是最干净的方案。
4.3 用模板库实际跑一个任务的现场记录
我拿系统提示词模板加代码生成模板跑过一个“新增用户列表接口”的任务，下面记录一下关键过程。
我先在终端启动 Claude Code，它会自动读取项目根目录的 CLAUDE.md。这时候我检查一下 AI 是否记住了项目背景，就问了一句“我们这个项目用的什么数据库”，它准确回答了 Prisma + PostgreSQL。这说明 CLAUDE.md 中技术栈部分的描述清晰到可以让模型准确抓取。
接下来我调用任务模板：
根据模板新增用户列表接口： - 接口功能：分页查询用户列表，支持按用户名模糊搜索 - 路由路径：GET /api/users - 入参说明：page（页码）、pageSize（每页数量）、username（可选模糊搜索） - 出参说明：{ list: User[], total: number, page: number, pageSize: number }AI 的响应速度很快，直接给出了路由文件、Service 层代码和 zod 校验规则。生成的代码里包含了我模板里规定的 ResponseWrapper 包装、错误处理和安全查询，几乎不需要改动。唯一需要手动修的，是它的分页逻辑在某些边界值处理上和项目现有风格略有出入，这个我顺手改掉就好。
整个过程大概 10 分钟，如果手写，同样的代码量可能需要 40 分钟以上。这里的差距主要来自：模板已经帮 AI 省去了“不了解项目背景”“猜测代码风格”这两个环节，它可以直接把精力放在实现逻辑上。
5. 常见问题与排查技巧实录
5.1 CLAUDE.md 没生效怎么办
这是使用模板库时最常遇到的问题，排查路径基本固定。第一步，确认文件在项目根目录，文件名大小写正确（CLAUDE.md，不要写成claude.md或Claude.md）。第二步，确认没有在子目录里放了另一个 CLAUDE.md 把根目录的覆盖了，特殊情况下这是有意为之，但多数情况下是历史遗留。第三步，确认编辑后重新启动了 Claude Code 会话，它不会在同一个会话内热加载更新后的 CLAUDE.md。
我最初就在这上面卡过挺久，以为是模板写错了，反复改内容都没效果，最后发现是压根没重启会话。这是个很蠢但很多人都会犯的错误。
5.2 模板生效了但 AI 输出还是不如预期
如果模板内容确实被加载了，但输出质量还是不稳定，问题大概率出在约束条件写得太模糊。比如你写“代码要优雅”，这个约束模型很难执行；改成“优先使用函数式编程风格，避免 class 组件；代码行数控制在 50 行以内；禁止直接修改 state”，它就非常明确。
模板里每条约束都应该是“可验证”的约束。执行完你看代码，能直接判断它有没有遵守。如果你自己都判断不了，模型更判断不了。
5.3 模板之间互相冲突的排查方法
模板多了以后，系统提示词和任务提示词之间可能出现互相矛盾的情况。比如系统提示词里说“注释要精简”，但任务模板里要求“每行关键代码都要注释”。这种冲突会让模型左右摇摆，输出结果有时偏这头有时偏那头，极不稳定。
排查方法很简单：把系统提示词 + CLAUDE.md + 任务模板三段内容贴到一个文档里，人肉检查一遍逻辑一致性。不要觉得这下意识检查的效率低，模板更新过程中最容易积累这种隐性冲突，每跑一个组合都验证一下，长期看是最省心的。
我后来在模板库的 README 里专门加了一节“模板优先级说明”，明确写了：任务模板里的具体指令 > CLAUDE.md 里的项目约束 > 系统提示词里的基础行为规范。这样模型即使遇到冲突，也有一个明确的仲裁规则可以参考。
5.4 几个容易忽视的实际细节
用模板库越久，越觉得细节决定成败。比如模板文件的换行符、编码格式要统一，否则在部分终端环境下可能出现乱码；模板文件名不要用中文，避免 git diff 显示异常；模板里的示例代码要保证能跑通，因为 AI 会模仿你示例里的写法，如果示例代码本身不规范，它会把这个不规范当样板学习。
还有一个实用技巧：模板库里常驻一个debug-template.md，内容很简单，就一句话：“请逐条列出你读取到的所有约束指令，并说明你接下来会如何遵守它们。”调试模板是否生效时，调用这个模板，AI 会把它的“理解”说出来，你能立刻定位是模板没被读取，还是被读取但理解歪了。这个模板我几乎每周都用，强烈建议你也加一个。
6. 模板库的进阶扩展方向
模板库做到后面，就不再是单纯的提示词集合了，它会逐渐变成一个“AI 协作规范库”。我目前在实际使用中，觉得有几个扩展方向非常值得投入。
第一是引入项目术语表。把项目里的专业名词、缩写、内部叫法做成一个术语对照表放进 CLAUDE.md，AI 生成代码时就会使用正确术语命名变量和函数，而不是凭空发明。这在业务复杂的系统里效果特别明显，比如“结算单”不要生成 settlement_order，术语表会告诉它用我们内部统一的 payment_voucher。
第二是做评审模板，把“代码审查”的过程标准化。我们的 review 模板里明确要求 AI 按安全性、性能、可维护性、测试覆盖四个维度打分，每个维度给出具体的问题和修改建议。实测下来，这种结构化的 review 比让它自由发挥更有参考价值，节省了团队不少评审时间。
第三是模板库和版本管理结合，每个模板的变更都走 PR 流程，review 通过才合入。这样模板本身的演进也有记录，回滚也方便，团队里有人改了模板导致别人使用出问题，能看到具体是哪个版本的改动引起的。
不过最重要的建议还是：别让模板库变成摆设，要让它真正嵌入到你的工作流里。我个人的习惯是每周花半小时“维护模板”：看看这周哪些模板高频使用、哪些从来没用过、哪些输出效果不好，做一轮增删改。模板库跟代码库一样，需要持续维护才有生命力。
我自己的体会是，模板化的收益是复利式的。第一周可能只省了半小时，但每多一个高质量模板，后面每次用到都在帮你节省时间，而维护它的成本几乎可以忽略不计。坚持用两三个月，你回头对比一下不用模板时候的开发效率，差别会非常明显。
