用 Claude Code 做开发的人越来越多了但我发现个普遍现象工具装好之后大多数人第一反应是敲一句 prompt 开干然后下一轮换机器、换仓库、换项目同样的问题又得重新解释一遍。我自己维护的 claude-code-templates 这个项目就是专门来解决这种重复解释问题的。它不是一个单纯收集提示词的文件夹而是一套能直接放进.claude目录、能被 Claude Code 自动加载的项目级模板体系覆盖个人记忆、项目说明、任务指令、工作流规则和常见编码场景的脚手架。这篇文章想把我在实际维护和使用这套模板库过程中的完整思路写出来为什么模板要按记忆层 指令层 流程层来拆而不是扔一堆 prompt.claude目录怎么布局才能让模型稳定读取任务模板、工作流模板各自适合什么场景以及最关键的——模板库怎么维护才不会越用越乱。无论你是刚接触 Claude Code还是已经用它产了段时间代码这套思路应该都能直接用上。1. 先明确模板库的价值边界压缩重复决策不是收集提示词1.1 单独的提示词为什么经常失效很多人对模板的理解还停留在把一段好用的 prompt 存下来下次复制粘贴。但实际上 Claude Code 这类终端编程工具和网页版对话有一个本质区别它每次启动时能看到的东西不止是你的 prompt还有整个工作目录、git 状态、文件内容以及通过 CLAUDE.md 注入的长期记忆。如果你只把一段 prompt 塞给它而没有配套的项目上下文那这段 prompt 大概率会给出泛泛而谈的回答。举个例子我早期写过一个生成 README的提示词里面详细规定了章节结构、语气、命令示例的格式。单独使用的时候模型经常忽略项目里的实际命令行自己编造一些不存在的参数因为 prompt 里只说了要写清楚安装步骤却没有告诉它本项目使用 pnpm所有命令必须从 package.json 中提取真实脚本。这说明单点提示词能约束输出风格却约束不了上下文缺失的问题。模板库真正要解决的是把每次都要重新交代的环境信息、项目约束、操作习惯变成默认值让模型每次进入项目都自带这些背景。1.2 模板要压缩的三类重复决策我把模板库要覆盖的内容分成三类这个分类直接决定了目录结构怎么设计环境类决策这个项目用什么包管理器、测试框架、代码风格、Node/Python 版本要求、是否 monorepo。这些信息每个项目都不同但每个项目内部是稳定的。任务类决策常见的开发动作比如提交信息怎么写、分支怎么命名、单元测试跑哪些命令、依赖升级之后要做哪些回归检查。这类决策在一个团队里基本是固定的值得固化。流程类决策涉及多个步骤或多文件的工作流比如新增 API 接口它天然包含路由定义、参数校验、文档更新、测试用例四个步骤再比如修改数据库表结构它包含迁移脚本、模型更新、查询语句回归、数据清理验证。这类流程如果每次靠临场发挥很容易漏步骤所以必须模板化。模板库的本质不是让 AI 说出正确的话而是让 AI 在没有收到额外指令时也能默认做出正确决策。这是我后来才想明白的一点模板的价值权重取决于它能替你做多少默认决策而不是文本有多精美。2. 模板库的最小骨架目录结构、加载机制与命名规范2.1 .claude 目录的布局Claude Code 在项目里会自动识别.claude目录中的内容。我推荐的最小骨架是这样的这也是 claude-code-templates 这个项目当前采用的布局.claude/ ├── CLAUDE.md # 个人级 / 全局记忆通常放用户目录见第3节 ├── commands/ # 斜杠命令模板 │ ├── commit.md │ ├── pr.md │ ├── add-api.md │ └── fix-test.md ├── agents/ # 子 Agent 定义 │ ├── backend.md │ └── release.md ├── skills/ # 技能包可按需引用 │ ├── unit-test/ │ └── db-migration/ └── hooks/ # 生命周期钩子可调用脚本 └── pre-commit.shcommands目录里的每个.md文件就是一个可通过/commit、/add-api这类快捷指令触发的内容块。agents目录用来定义专业角色比如后端开发 Agent、发版 Agent它们可以各自维护独立的记忆和操作偏好。skills目录放技能包比如数据库迁移模板其中含说明文件和示例脚本。hooks则是在特定事件比如提交前自动执行的脚本。这套目录不是凭空设计的它的核心思想是按使用方式分区而非按主题分区。主题分区容易造成混乱比如一个数据库模板到底属于命令、技能还是 Agent 记忆而按触发方式分区就清晰是人主动敲/xx用还是模型在特定场景自动想起还是某个生命周期节点自动触发。2.2 让模板能自动加载的关键路径Claude Code 的记忆加载路径主要分两层。个人级配置放在~/.claude/CLAUDE.md它会跟随用户在所有项目中生效适合写我习惯用什么风格、我禁止用什么命令这类跨项目偏好。项目级配置放在项目根目录的CLAUDE.md或.claude/CLAUDE.md适合写这个仓库特有的事实。两层的优先级关系是项目级内容会覆盖或补充个人级内容所以全局习惯 项目约束的组合是一个很好的配置策略。我在模板库里专门放了两个层级的模板文件项目的 CLAUDE.md 模板里会写明所有 crate 用 snake_case 命名、所有数据库访问必须走 repository 层、修改公共接口前必须通知前端组等。而个人级模板写的是commit message 遵循 conventional commits、代码注释用中文还是英文、遇到不确定需求先列出假设再动手。看起来简单但真正稳定运行的模板库靠的就是这个清晰的两层记忆结构。另外要注意一个细节CLAUDE.md文件的头部最好写一行本文件是项目记忆不是执行指令只有在需要判断项目约束时参考它。原因后面我会展开讲模型在任务执行过程中可能会把记忆文件当成待执行任务处理导致每次对话都复述一遍项目规则干扰效率。2.3 命名规范如何定模板文件名看起来是小事但它决定了两个东西斜杠命令好不好记、模型在索引文件时能不能一眼看出用途。我的命名规范是动词开头、单一职责commit.md表示生成提交信息add-api.md表示新增 API 接口fix-test.md表示修复测试。避免用utils.md、helper.md这种含义模糊的名字也不要让一个模板同时承担生成接口生成测试生成文档三个功能。对于skills目录下的技能包命名要更具体一点比如db-migration/、unit-test/、dependency-audit/。技能包内部一般包含一个说明自身使用边界的SKILL.md文件加上示例文件或脚本。这里有一个容易踩的坑技能包文件夹名会用连字符还是下划线实测下来连字符在斜杠命令和引用短语中更自然下划线在某些 shell 脚本中更容易引起转义问题所以统一用连字符。命名规范决定的是可发现性。这个听起来很虚但实际维护超过 20 个模板之后你会发现很多时候不是没有模板而是你根本想不起来某个模板叫什么。动词开头 单一职责的命名方式配合claude命令列表的自动补全能让你在三四个月后依然找到需要的模板。3. 个人级与项目级 CLAUDE.md 模板上下文管理的两种深度3.1 个人级 CLAUDE.md写自己的操作习惯个人级配置默认位于~/.claude/CLAUDE.md。这一层的模板要回答的问题不是这个项目怎么做而是我这个人怎么干活。我在模板里沉淀的三类偏好供你参考命令偏好我不希望 AI 修改文件后自动执行测试所以明确写了修改代码后不要自动运行测试先展示 diff 给我确认。这看起来反效率但对于代码库较大、测试耗时的项目这个设定能避免它陷入改一个文件跑一次全量测试的低效循环。语言偏好我给代码注释、commit message 都设定了默认语言。这里要具体到commit message 用英文写但代码内注释用中文写否则模型会凭感觉混用。工具链偏好我最常用 pnpm、uv、cargo 这类现代工具所以个人级 CLAUDE.md 里明确写了安装依赖优先使用各语言官方的现代包管理器避免使用全局安装。个人级模板的关键是你得诚实面对自己的使用习惯。我见过有人把个人级 CLAUDE.md 写成了教科书列了三十多条规则结果模型反而不知道怎么执行。好的个人级配置应该控制在 10 到 15 条以内每条都是你踩过一次坑之后不希望它再犯的硬规则。3.2 项目级 CLAUDE.md写项目持久事实项目级 CLAUDE.md 是模板库中最重要的一块因为它是模型判断当前代码库里发生了什么的依据。我在 claude-code-templates 项目中维护了一份项目级模板骨架核心字段如下模块内容示例项目概述一句话说明项目定位内部 CLI 工具用于批量处理发票数据技术栈语言、框架、关键依赖及版本Node 22 TypeScript 5 Fastify包管理用 pnpm目录结构关键目录的职责src/services 放业务逻辑test/ 放集成测试常用命令启动、测试、构建、Lint 的真实命令pnpm dev / pnpm test / pnpm build / pnpm lint代码约束必须遵循的硬性规范所有错误必须通过 Result 返回禁止抛异常工作流涉及多人协作的流程约定PR 必须关联 issue变更必须带 changeset项目级模板的核心不在于格式多么精美而在于它必须和真实仓库保持同步。模板库里可以放一个通用的 CLAUDE.md 模板但每个项目使用时要让人手工核对一遍常用命令表和实际的 package.json。我曾经遇到过模板里写的测试命令是npm test但项目实际用的是pnpm vitest run结果模型每轮测试都用错命令白白浪费了几次调用。3.3 两个层级的组合原则全局优先项目覆盖个人级和项目级配置的组合原则我总结为全局优先项目覆盖。所有项目共通的东西放个人级只有某个项目独有的事实才放项目级。千万不要把个人偏好复制到每个项目里那会让 CLAUDE.md 越来越臃肿。实际操作中我建议用一小段合并约定来兜底在项目级 CLAUDE.md 的末尾写一行本项目技术栈与命令以本文件为准个人级配置中的命令偏好仅作为兜底。这样当个人级配置说优先使用 pnpm而项目由于历史原因必须使用 npm 时模型能够明确判断以谁为主不至于在两份配置之间反复横跳。还有一个灵活技巧在项目根目录之外的子项目里可以用更小的.claude/CLAUDE.md覆盖根级配置。比如 monorepo 里前端工程和后端工程的技术约束完全不一样在后端目录放一个本目录是 Go 服务所有测试命令以这里为准的迷你配置文件效果比在整个仓库根配置里堆砌分支逻辑更清晰。4. 任务模组与工作流模板把多步动作变成一次指令4.1 斜杠命令常见动作的快速入口.claude/commands/是模板库中最容易见效的部分。它的原理很简单你输入/commit模型读取commit.md的内容结合当前 git diff 生成提交信息。我在 claude-code-templates 里维护的命令模板有三个等级第一级是纯文本指令适合依赖上下文判断的任务。比如commit.md的内容只有几行先看git diff --stat和git diff理解改动范围再按 conventional commits 规范生成提交信息最后展示给用户确认不要直接执行。这类模板不需要任何参数因为所需信息全部来自当前工作区状态。第二级是带状态的指令适合需要加载额外文件的任务。比如refactor.md它要求模型先读CLAUDE.md中的代码约束再找到目标函数的所有调用点列出一个重构影响面清单最后才开始动手。我踩过的一个坑是如果不让模型先列影响面它经常只改目标文件本身导致调用方类型报错。第三级是组合指令适合跨文件的复合任务。比如add-api.md内部定义了一个严格顺序确认路由归属 → 实现 handler → 添加参数校验 → 补测试 → 更新 API 文档。模型通过读取这个模板相当于执行一个必含步骤清单漏掉任何一步都算完成得不好。4.2 工作流模板把步骤清单固化成规则集斜杠命令适合用户主动发起的场景但 Claude Code 里还有另一类需求希望在某个任务被发现时自动进入多步流程。这类需求我用agents/目录下的工作流模板来处理。以新增数据库迁移为例我在agents/db-migration.md里定义了一个后端架构师 Agent它接到的任务指令不是帮忙建表而是一整套约束读取现有迁移文件命名规范 → 分析当前表结构与关联关系 → 生成新的迁移 SQL → 同步更新 ORM 模型 → 补充 down 迁移脚本 → 提醒用户执行pnpm migration:up。这个模板和斜杠命令的区别在于Agent 拥有独立记忆它在处理数据库任务时不会被通用开发指令干扰而且可以配置为当对话中出现建表、改表、加索引等关键词时自动被引用。工作流模板的核心设计原则是把顺序写死把判断留给模型。顺序写死是为了不漏步骤判断留给模型是为了适应真实代码的差异。比如生成迁移 SQL不会规定每一列怎么写而是让模型根据现有模型文件判断字段类型、可空性和索引策略。4.3 模板中的变量、参数与上下文传递斜杠命令模板支持参数这在实际使用中非常关键。语法是在文件名后跟着参数模板内部用$ARGUMENTS引用。以add-api.md为例用户可以输入/add-api 创建订单接口POST /api/orders模板内部用$ARGUMENTS拿到这段描述再结合工作区代码推断接口所需字段。但这里有一个重要经验模板不要过度依赖参数因为用户往往懒得打完整参数。我第一次设计模板时规定了一堆必填参数比如 method、path、description结果用了几次就发现每次都要打一长串最终选择放弃。后来我改成参数只是意图说明具体路径从问题描述推导模板反而被团队接受。上下文传递还有一个容易忽略的环节斜杠命令执行完毕后模型的分析结果应该写入会话上下文而不是只输出到终端。所以我在模板里常加一句完成本任务后用三句话总结变更内容方便后续对话引用。这句话看起来多余但它让后续的再帮我改一下刚才那个接口这类追问变得非常顺滑。5. 实战拆解模板库如何把一次 API 对接任务从半小时压到五分钟5.1 场景设定一个典型的第三方支付接入我拿最近在 claude-code-templates 上实测的一个场景来演示。假设项目需要新增一个第三方支付回调接口业务需求是接收支付平台的回调通知、验签、解析订单号、更新订单状态、返回确认应答。这个任务在过去没有模板支撑时我通常会自己手写步骤先看现有支付模块的代码结构找到订单模型再配路由……每一步都要在对话里给 Claude Code 交代上下文。半小时是常态如果中间模型理解偏了可能要往返四五轮。现在我在项目里维护了agents/payment-integration.md和commands/add-webhook.md两个模板这套流程被压缩成了四步操作。5.2 执行过程模板是怎么一步步起作用的第一步我在终端输入/add-webhook 支付回调。add-webhook.md模板被加载它要求模型完成以下动作搜索项目里已有的 webhook 或 callback 相关目录评估是新建模块还是复用现有入口读取当前支付相关的 Service确认验签逻辑是在 controller 层还是 service 层列出影响范围包括路由文件、DTO 定义、订单状态枚举实现接口验签、解析参数、更新订单状态添加针对性的单元测试至少覆盖验签失败和重复通知两个分支用一句话总结变更提醒人工复核。这个模板之所以高效是因为它把找代码结构这件最消耗上下文的事变成了默认动作。模型通过在模板指令下搜索文件结构很快就定位到项目的支付模块位于src/payments/并且发现验签工具函数已经存在于src/payments/utils.ts中。如果没有模板指令它可能会直接从我该建哪些文件开始想思路完全不同。第二步在处理过程中模型发现订单状态枚举里缺少PAYMENT_CONFIRMED这个状态。按照普通对话流程我大概率需要新开一轮对话让它处理但因为我预设的payment-integrationAgent 记忆里写了修改枚举必须同步检查所有 switch 分支它主动搜索了所有引用这个枚举的代码发现有两个地方需要补全然后一并处理了。这个主动的额外动作正是工作流模板的收益——它把隐性约束嵌入了 Agent 的记忆而不是等我这个人类去发现。第三步模型完成测试后自检了一下重复通知场景。正常情况下这需要我主动提醒但模板中规定了所有支付回调必须考虑幂等。它自动在订单表里查找是否有callback_id字段没有则通过添加一个payment_callbacks表来记录回调 ID 和通知状态。这一步虽然在执行模板之前完全不可预知但模板中的幂等规则让我不用在对话中额外强调。5.3 效果和边界模板能加速什么不能替代什么整个流程跑通大约花了不到五分钟最终提交包含一个路由、一个 Service 方法、一个 DTO、一次数据库迁移和两组测试。而历史经验中同样的任务人工推进时需要完成向模型解释代码结构、强调验签逻辑的位置、指出订单状态可能缺失、提醒幂等要求……省掉的每一轮对话本质上都是模板库的执行收益。不过要清楚模板的边界它能帮你规范流程、提醒约束但不能替你做架构决策。我遇到的情况是模板要求评估是新建模块还是复用现有入口这一步模型给出了两个方案并让我选择而不是擅自决定。这是我在模板里特意的设计——凡涉及要不要引入新目录、要不要改公共接口这类有长期影响的决策模板强制先问人只有那些影响可控、可以快速回滚的局部修改才可以自动执行。6. 模板库的维护与迭代真实环境里踩过的坑6.1 模板和真实代码脱节是最大的坑模板写出来之后放在那里它不会自己更新。最典型的场景是项目从 Fastify 换成了 Encore但CLAUDE.md里还写着框架为 Fastify路由请参考 src/routes.ts。结果模型每次生成新接口都按旧的框架写法报错了还不知道为什么。我后来养成了一个习惯每次重构涉及框架、命令、目录结构时第一时间更新相关模板并把更新文档/模板作为重构任务的收尾步骤写在工作流规则里。另一个脱节场景是模板之间的互相引用失效。比如commands/api.md引用了一个叫统一错误码规范的约束但这个规范已经改过了导致模型按旧规范生成代码测试阶段才发现错误码体系早已迁移。这比单文件过期更隐蔽因为模板本身看起来没什么问题。解决办法是在模板头部写明最后验证时间和依赖文件路径并周期性抽查。6.2 模板库的版本管理把它当代码看待claude-code-templates 这个项目本身就应该用 git 管理而且我建议直接使用 commons 仓库的方式模板的变更必须走 PR配套一个CHANGELOG.md说明每个模板的改动理由。很多人觉得模板是小东西改一下无伤大雅但模板恰恰是低频率、高风险的文件——它平时不出声一旦出错就是系统性出错所有用到它的生成任务都会受牵连。我之前犯过的一个错误是为了快速修复直接改了团队共享模板库里的一个规则没通知任何人结果另外两位同事的生成代码风格都变了review 时才发现。从那以后我规定模板变更必须带说明且至少有一名同事 review。这里推荐一个简单可行的版本方案级别使用场景版本策略dev正在实验的新模板本地分支不入主分支stable已被三个以上任务验证合入 main并标注版本号deprecated被新方案取代的模板移入 deprecated/ 目录保留 90 天6.3 模板避免腐化的日常维护节奏我给这个模板库定的维护节奏是三件事季度审查、任务后更新、废弃机制。季度审查是指每三个月过一遍所有模板对照当前项目实际代码删除已经无用的更新过时的。这个周期不能太长否则模板和代码之间的偏差会累积到失控。任务后更新是指每次用模板执行完一个较大任务后如果发现模板漏了某一步或者某一步的描述让模型产生了错误理解就当场修改模板并记录修改原因。废弃机制比想象中重要给模板写上适用场景和已不适用场景两行可以避免后来者在错误场景下套用模板。最后我想分享一个维护上的小技巧用 Claude Code 本身来审查模板库。定期让它读取所有模板文件找出重复、互相矛盾、措辞模糊的规则。模板库的本质是让模型少踩坑而 AI 最擅长的事情恰恰是发现文本之间的不一致。这个循环跑起来之后模板库的价值会越来越大而维护成本并不会同步上涨。