如果你受够了每次启动新项目时都要在终端里花十分钟向 Claude Code 解释技术栈、代码规范、测试要求然后不到二十条对话它又忘了一半——那这篇关于 claude-code-templates 的经验分享应该能帮到你。我去年开始把 Claude Code 作为主力开发工具最初也是裸配每开一个新仓库就在对话里手写上下文。真正让我决定做模板库的契机是连续三个项目里被同一个问题反复刺痛——AI 在 A 项目里早就学会的规范到 B 项目又要重新教。于是我开始把分散在对话记录里的“教它做的事”整理成结构化配置最终形成了一个可以一键复用的模板仓库。这套 claude-code-templates 不是提示词打包而是包含 CLAUDE.md 模板、自定义命令、钩子、子代理这几个层面的完整配置体系。这篇内容适合两类人一类是刚接触 Claude Code、想直接从第一天就建立起规范工作流的新手另一类是已经在用但觉得每次配置成本太高、AI 输出不稳定、希望把个人经验固化成工程资产的进阶用户。我会把模板库的拆解、搭建过程、真实效果、失效边界和迭代方法全部讲透。1. 从裸配到模板库我为什么不再手写 CLAUDE.md1.1 裸配时的三个痛点最直接的痛点叫做“重复教学”。新项目开工我要在对话里把项目背景、技术栈、关键约束从头讲一遍这是一个 FastAPI 项目、数据库用 SQLAlchemy 2.x、接口必须带 pydantic 模型、测试跑 pytest。这些信息看起来不多但每开启一个新对话就要重新讲一遍。更要命的是AI 不会真的记住几十轮对话之后它会突然生成一段同步数据库访问代码而我在前面已经纠正过五次。第二个痛点是规范不可继承。我在项目 A 里磨合出来的编码约定到了项目 B 完全归零。比如项目 A 里我花了大量口舌让 AI 学会“所有返回时间统一用 UTC”、 “日志必须走 logger 而不是 print”它在 A 项目里表现得很好但切换到 B 项目又会故态复萌。如果团队的每个成员都在各自的对话里教 AI 相同的事那这些经验就被彻底浪费了。第三个痛点是输出随机性。同样的指令在不同对话里 AI 的行为差异很大。有时它会严格遵守我在开头写的约束有时则完全放飞取决于它当时在上下文里读到了什么。裸配状态下整个开发过程像是在和一只记忆力忽好忽坏的猴子合作。配置文件的意义就是把这种随机性压到最低。裸配听起来自由但真正的成本被长期低估了每次开启新任务的“初始化成本”都在重复产生而且这些成本是隐性的你不会在一次对话里明显感觉到只会在频繁切换项目时被慢慢磨掉耐心。1.2 CLAUDE.md 的工作机制Claude Code 的配置枢纽是 CLAUDE.md。简单说它是一份每次会话都会自动加载的指令文件相当于 AI 的“入职手册”。普通的对话内容会随着上下文窗口滚动被遗忘但 CLAUDE.md 里的内容每一条消息都会被重新读取所以它天然适合承载那些“始终有效”的规则。我经常用新员工入职做类比。你让一个新同事干活有两种方式一种是每天早上口头交代一遍流程另一种是丢给他一本操作手册让他随时查阅。对话上下文就是口头交代CLAUDE.md 就是操作手册。显然手册更稳定、更可追踪、也更容易被团队统一更新。Claude Code 会从多个位置读取 CLAUDE.md用户级的~/.claude/CLAUDE.md对所有项目全局生效项目根目录的CLAUDE.md则只影响当前项目。这种分层机制非常关键——它天然支持“通用规则放全局项目规则放仓库”的结构也正是模板库得以组装的基础。很多人误以为 CLAUDE.md 只是“写得好一点的提示词”这个理解差很远。提示词是一次性的对话输入而 CLAUDE.md 是持久的、版本化的、可以随代码仓库一起分发的规则文件。它应该被当成代码的一部分来对待而不是聊天开场白。1.3 从“一份配置”到“一套模板库”既然 CLAUDE.md 这么好用那每个项目写一份不就行了吗问题在于项目之间的差异太大了。有一个 Python 后端、有 TypeScript 前端、有内部运维脚本每一类的语言习惯、工具链、测试方式都不同。如果写一份放之四海皆准的配置要么内容过于泛泛要么对特定项目充满噪音。所以我做的 claude-code-templates 不是“一个模板”而是“一套模板的组合方案”。基础层放所有项目都适用的通用规则语言层放 Python 或 TypeScript 的惯例框架层放 FastAPI、Next.js 这类具体技术栈的约束。使用者按需组合就像搭积木。这套方案的目标非常明确把新项目的初始化时间从半小时压缩到一分钟以内。我想要的效果是新建一个仓库、跑一个 bootstrap 脚本、花半分钟回答两三个问题然后这个项目里的 Claude Code 就已经“懂”了技术栈、规范、测试方式、提交前要跑哪些检查。接下来要做的就是直接开始写功能。2. 模板库的四大核心组件拆解2.1 三层模板模型base、language、framework模板库的第一个核心组件是 CLAUDE.md 本身但我没有把它做成单一文件而是拆成了三个层级。这个设计决定是在实际使用中一步步逼出来的。base 层是任何项目都不能违反的底线。比如不伪造测试数据、不把密钥硬编码进代码、不盲目执行来源不明的命令、涉及生产环境的操作必须先提示风险、代码审查必须关注安全而不只是功能正确性。这些规则与语言和框架无关无论你写的是 Python 还是 Go它们都成立。language 层解决的是语言特有约定。以 Python 为例模板里会写明类型标注必须完整、使用 uv 做依赖管理而不是裸 pip、测试统一用 pytest、Lint 工具配置在 pyproject.toml 里。这些内容放 base 层不合适因为 TypeScript 项目根本不需要它们。framework 层则是更具体的框架约束。FastAPI 项目里要写数据库访问统一走异步 SQLAlchemy、接口必须有 pydantic 请求与响应模型、业务逻辑放 service 层Next.js 项目里要写服务端组件和客户端组件的边界、路由处理方式、环境变量的读取方式。这层内容最细也最贴近具体代码库。层级内容范围典型条目base跨语言、跨团队的通用规则安全红线、通用编码规范、AI 行为边界language某一种语言的约定包管理器、测试框架、格式化工具framework具体技术栈的项目约束ORM 用法、接口结构、目录分层这三个层级在模板库里分别对应base/、langs/、frameworks/三个目录使用的时候按项目类型拼接。拼接方式不是物理上的文件合并而是让项目经理在初始化时决定加载哪些片段然后在生成的项目 CLAUDE.md 里分区块呈现。2.2 自定义 Slash Commands把高频动作变成快捷键CLAUDE.md 解决的是“AI 默认应该知道什么”而自定义斜杠命令解决的是“AI 应该怎么执行特定任务”。我是在做了一次大型代码审查之后才意识到这层需求的——每次让 AI 做 Code Review我都要重新描述审查重点、输出格式、严重级别定义而且每次描述得还不完全一样。显然这类高频且流程固定的任务应该被固化下来。Slash Commands 的实现方式很简单把 Markdown 文件放进.claude/commands/目录文件名就是命令名。比如建一个review.md就可以在对话中输入/review来触发。命令文件支持标准的 YAML frontmatter用来设置描述信息、参数提示等。下面是模板库里review.md的简化版本可以直接拿去用--- description: 对当前分支改动进行一次 Code Review argument-hint: [optional commit range] --- 请对当前分支的改动进行一次完整 Code Review。重点检查 1. 是否引入未处理的异常或过宽的异常捕获 2. 是否存在安全风险SQL 注入、命令注入、敏感信息泄露 3. 事务边界是否合理是否可能产生死锁或数据不一致 4. 是否有明显可优化的性能问题 输出要求 - 按严重程度从高到低排序 - 每个问题必须包含位置、问题描述、修复建议 - 如果没有发现问题明确说明“未发现需要处理的问题”我用过的命令集中产出比最高的几个是/review做变更审查、/test生成并执行测试、/docs补接口文档、/migration生成数据库迁移脚本、/changelog汇总变更日志。设计命令模板的原则很简单职责单一一个命令只做一件事输出格式显式声明避免 AI 给你一段泛泛而谈的废话。2.3 Hooks 配置把规则从“建议”变成“强制”如果说 CLAUDE.md 和命令模板是“告诉 AI 应该怎么做”那 hooks 就是“不管 AI 想不想做机制上都拦住它”。这是模板库里最有价值也最容易被忽视的部分。hooks 是 Claude Code 的事件驱动机制在某些动作发生时自动执行外部命令。我用的最多的是PreToolUse和PostToolUse两个事件。前者在 AI 调用工具之前触发适合做安全检查后者在工具执行完之后触发适合做自动格式化。一个典型的例子是拦截危险命令。团队规定不允许在未确认的情况下执行git push --force与其指望 AI 每次都记住这个约束不如在 Bash 工具执行前加一道钩子{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: if echo \$TOOL_INPUT\ | grep -qE git push --force|rm -rf /; then echo 危险命令需要人工确认; exit 2; fi } ] } ] } }这段配置的意思是当 AI 准备执行 Bash 命令时先检查命令内容如果命中危险模式直接阻止执行并提示人工确认。注意exit 2代表阻断exit 0则放行。这种机制把安全规则从“软性建议”变成了“硬性约束”。但 hooks 也是一把双刃刀。配置过严会频繁误伤正常流程比如你想让 AI 在特殊情况下执行一次git push --force修复线上分支结果被自己的钩子拦住了还得回头去临时改配置。我的经验是hooks 默认用于“告警要求确认”而不是“无条件禁止”除非那条规则绝对没有例外。2.4 子代理角色复杂任务的小团队模式用过一段 Claude Code 的人都有一个共同感受在一个超长会话里塞太多任务对话的指令遵循度会越来越差。原因很好理解单一上下文窗口里塞进了太多不同职责的内容互相干扰。解决办法之一就是子代理。子代理是独立的、拥有自己系统提示词的执行单元。你可以定义reviewer只负责代码审查定义architect只负责设计技术方案定义documentation-writer只负责写文档。主对话负责调度子代理负责专项执行相当于给 AI 配了一个分工明确的小团队。在我的模板库里子代理定义放在.claude/agents/目录每个角色一个 Markdown 文件。主 CLAUDE.md 中只声明“什么场景下启用哪个角色”比如大规模重构前启用architect提交前启用reviewer。这种做法的收益非常明显。以前让 AI 既写功能又审查代码审查质量总是被写功能的任务带偏现在把职责拆开之后每个角色的上下文都专注于自己的领域审查意见的质量高了一个量级。对于大型项目来说这是最值得投入的一部分。3. 从零搭建模板库目录结构与可直接抄的实例3.1 目录结构设计按需加载是灵魂搭建模板库的第一步不是写内容而是定结构。结构没定好后面每加一个配置都会觉得别扭。我的目录是长这样的claude-code-templates/ ├── base/ │ ├── CLAUDE.md # 基础行为规范 │ └── settings.json # 默认 hooks 配置 ├── langs/ │ ├── python/ │ │ └── CLAUDE.md │ ├── typescript/ │ │ └── CLAUDE.md │ └── go/ │ └── CLAUDE.md ├── frameworks/ │ ├── fastapi/ │ │ └── CLAUDE.md │ ├── nextjs/ │ │ └── CLAUDE.md │ └── react-native/ │ └── CLAUDE.md ├── commands/ │ ├── review.md │ ├── test.md │ ├── docs.md │ └── migration.md ├── agents/ │ ├── reviewer.md │ └── architect.md └── bootstrap.sh这个结构的核心思路是“按需加载”。base始终要带langs根据项目语言选一个frameworks更特殊只有用到对应技术栈才带。commands和agents是跨项目通用的公共资产无论项目类型是什么都可以直接复制进.claude/目录。我强烈不建议把全部内容写进一个几万字的 CLAUDE.md。文件越长AI 在具体决策时越难命中关键规则。打个比方一本操作手册如果包含了所有设备和所有场景的全部操作说明那新员工要在里面查一条具体规则反而比直接问老同事更慢。模板库应该像工具箱用的时候只拿需要的工具。3.2 一份可运行的 Python 项目 CLAUDE.md 模板下面是一份我实际在用的 Python 后端项目模板由 base langs/python frameworks/fastapi 拼接而成。这里我把拼接后的结果完整贴出来方便你直接抄。# 项目角色 你是这个 FastAPI 项目的高级 Python 工程师。你的职责是在不偏离现有架构的前提下实现功能。 # 代码规范 - 所有函数和方法的参数与返回值必须显式标注类型 - 数据库访问统一走 SQLAlchemy 2.x 异步风格禁止使用同步 Session - 新增接口必须包含 pydantic 请求模型与响应模型禁止直接返回 ORM 对象 - 业务逻辑写在 service 层路由文件里只做参数解析和结果返回 - 日期时间统一使用 UTC序列化时明确指定时区 # 测试规范 - 新增功能必须补 pytest 测试覆盖正常流程和至少一个异常分支 - 测试文件放在 tests/ 目录遵循 test_module.py 命名 - 测试命令统一使用pytest -q # Lint 与格式化 - 代码必须通过 ruff check - 禁止使用 print 输出业务日志统一走 logging # 提交前验证 - 必须依次运行ruff check . pytest -q - 如果存在数据库迁移先执行 alembic check 确认迁移状态这份模板不长但每条都是强约束。写模板时最忌讳的就是列一堆模棱两可的“建议”比如“尽可能写好代码”这种话对 AI 没有任何约束力。每一条规则都应该能被机器或审查者明确判定“遵守了”或“没遵守”。你可能会问为什么不用path指令在 CLAUDE.md 里引用模板库的文件技术上可行但我发现直接把解析后的内容生成进项目仓库更可靠。团队协作时每个开发者 clone 项目就能拿到完整的配置不依赖每个人本地都有一份模板库。这也是“项目级配置跟随仓库走”的原则。3.3 命令模板的编写方法与调试技巧命令模板的编写有个容易被忽略的细节frontmatter 里的description不只是给人看的它会出现在斜杠命令的提示菜单里直接影响 AI 在决定是否调用这个命令时的判断。所以 description 要写得像函数签名一样准确让别人一看就知道这个命令是干什么的。写命令正文的时候最有效的技巧是“给输出格式”。很多人写的命令只描述任务不定义输出结构AI 给的回答五花八门。我在review.md里明确写“按严重程度从高到低排序”“每个问题必须包含位置、描述、修复建议”效果立竿见影。调试命令模板的推荐路径是先在一个测试项目里实际跑一遍看 AI 的输出是否达到预期。如果它给的是泛泛而谈的内容多半是命令里的指令还不够具体如果它严格遵守了格式说明命令的设计到位了。我一般会建一个叫sandbox的专用测试仓库专门用来试命令和模板避免在真实项目上翻车。3.4 接入流程全局配置与项目配置两条路模板库接入 Claude Code 有两条路分别解决不同的问题。全局接入是把base层的配置和常用命令放进~/.claude/目录让本机的所有项目默认生效。适合放跨项目通用的内容比如安全红线、通用编码风格、全局可用的/review命令。好处是每个新项目开箱即用坏处是它不是跟着仓库走的团队其他人无法共享。项目接入是在每个仓库里生成一份.claude/目录把所有项目相关的配置都提交进 git。团队协作时每个人 clone 下来就有完全一致的配置这是最可靠的共享方式。项目接入通常靠一个初始化脚本完成下面是我在模板库里用的bootstrap.sh#!/usr/bin/env bash # usage: ./bootstrap.sh python fastapi ./my-project set -euo pipefail LANG${1:-python} FRAMEWORK${2:-} PROJECT_DIR${3:-.} TEMPLATE_ROOT$(dirname $0) if [ ! -d $PROJECT_DIR ]; then echo 项目目录不存在: $PROJECT_DIR exit 1 fi mkdir -p $PROJECT_DIR/.claude/commands $PROJECT_DIR/.claude/agents # 生成项目级 CLAUDE.mdbase language framework { cat $TEMPLATE_ROOT/base/CLAUDE.md echo cat $TEMPLATE_ROOT/langs/$LANG/CLAUDE.md if [ -n $FRAMEWORK ] [ -f $TEMPLATE_ROOT/frameworks/$FRAMEWORK/CLAUDE.md ]; then echo cat $TEMPLATE_ROOT/frameworks/$FRAMEWORK/CLAUDE.md fi } $PROJECT_DIR/CLAUDE.md # 复制公共命令与 hooks cp $TEMPLATE_ROOT/commands/*.md $PROJECT_DIR/.claude/commands/ cp $TEMPLATE_ROOT/base/settings.json $PROJECT_DIR/.claude/settings.json cp $TEMPLATE_ROOT/agents/*.md $PROJECT_DIR/.claude/agents/ echo 模板已写入 $PROJECT_DIR这个脚本做的事情很简单拼接 CLAUDE.md、复制命令目录、复制 settings.json。我特意不把它做得很复杂因为模板库的核心价值在于内容质量而不在于初始化脚本的花哨程度。脚本越简单越不容易出错也越容易被团队成员理解和修改。3.5 模板设计的三个原则第一少而准。一份高质量的 CLAUDE.md 通常控制在 30 到 80 行之间。规则太多AI 把握不住优先级规则太少约束力明显不足。取舍的标准是这条规则是否会在实际开发中被反复用到。第二负面清单优先。正面建议容易被 AI 理解成“最好这样做”负面约束则更明确——哪些事绝对不能做。比如“禁止使用同步数据库访问”“禁止把 ORM 对象直接作为接口返回”。负面清单能有效压缩 AI 的探索空间把行为收敛到安全范围。第三模板必须可测试。我所谓的可测试指一个开发者仅凭模板就能判断一段代码是否合规。如果一条规则需要读完整本架构文档才能判断对错那它对 AI 来说也太难了。规则要尽量机器可判哪怕不能自动执行至少也要能在 Code Review 时一眼看出来。4. 模板库在真实项目中的效果与边界4.1 一个真实项目前后的效果对比我在一个内部 FastAPI 工具项目上完整经历了从裸配到模板化的过程前后效果差异非常明显。简单说说迁移前的情况每次发起一个新对话我都要在前面几条消息里反复强调“不要生成同步数据库访问代码”“接口带上 pydantic 模型”“时间统一用 UTC”。即便如此这些约定还是会在长对话中不断被突破平均每三次会话就有一次需要人工纠正。迁移到模板库之后这些纠正在对话里几乎消失了。我把之前教过的几条规则写进了 CLAUDE.mdAI 在启动时就自带这些约束。更明显的变化是接口输出的一致性。以前生成的接口响应模型五花八门现在统一走 pydantic 模板后代码风格像出自同一人之手。迁移前常见对话纠正模板中的对应约束“这里不要用同步 Session要异步”数据库访问统一走 SQLAlchemy 2.x 异步风格“接口不要直接返回 ORM 对象”新增接口必须包含 pydantic 请求与响应模型“时间串格式不对要带 UTC 时区”日期时间统一使用 UTC序列化时明确指定时区数据说话的话我大概统计过迁移后人工干预的频率降到了原来的三分之一以下。这不是因为 AI 变聪明了而是因为它不再需要靠上下文记忆来维持行为规范模板承担了这部分记忆。4.2 模板失效的高发场景与应对办法模板不是万能的我踩过不少坑总结下来有四类高发场景。模板过度膨胀。这是最容易犯的错误。一开始觉得规则多多益善把几十条经验全塞进 CLAUDE.md结果 AI 反而抓不住重点后面几条规则在行为中几乎体现不出来。解决办法是定期做减法超过 100 行的模板就该仔细检查逐条问自己这条真的常用吗删掉会有什么后果模板和实际代码库脱节。有一次我在模板里固定写了“使用 pip 进行依赖管理”但当时项目已经全面切到 uvAI 照着模板操作后反而制造了很多混乱。模板不是文物它必须跟着项目的技术演进同步更新这一点靠季度审查来保证。团队使用不一致。这个问题在多人协作时最容易出现只有一个人把模板提交进仓库其他人要么没拉最新分支要么本地在旧版本上运行效果自然参差。我的经验是模板配置必须作为项目代码的一部分提交进 git并且约定所有新加入的开发者从 bootstrap 脚本开始初始化项目。hooks 误伤正常流程。我曾经配置过一条禁止git push --force的硬阻断后来要做一次紧急分支修复AI 完成任务后所有命令都被钩子拦下来卡了十几分钟。现在我的 hooks 策略改成了“告警并要求确认”而不是直接禁止。安全规则要保留人工解除的通道。4.3 哪些项目根本不值得套模板不是所有项目都适合上模板。我的原则是初始化成本高于每次重复教学成本时就不要套。一次性脚本就是典型。跑完就删的临时工具花两分钟在对话里交代完事比建模板库、跑 bootstrap 划算得多。极早期的原型项目也不适合套太重的模板。这个阶段的代码每天都在剧烈变化规范本身就没有定型模板反而成为探索的束缚。还有一个容易忽略的场景已经进入纯维护状态、很久没有新增功能的项目。这种项目里 AI 的主要工作是查问题、改小 bug模板带来的收益有限。判断标准很简单如果你每个星期只需要和 Claude Code 聊一两次模板化的意义不大如果你每天都靠在它身上写代码那模板值得认真做。5. 维护与迭代模板库是“活”的工程资产5.1 从对话里沉淀新的模板增量模板库建成之后真正的工作才刚刚开始——让它持续进化。我发展出了一套很笨但很有效的迭代方法每周抽一点时间翻看最近的对话记录找到那些“我纠正过 AI 两次以上的地方”然后把这条教训写进模板。举个例子。有段时间 AI 连续几次在生成接口序列化代码时把日期时间序列化成带时区偏移的字符串被纠正过三次。这个模式出现得太频繁了我就在 Python 模板里加了一条“日期时间统一使用 UTC序列化时明确指定时区。”加完之后同类问题几乎再也没出现过。但也要注意不是所有错误都值得写进模板。有些是一次性的奇怪操作写进去只会增加噪音。我给自己定的筛选标准是必须在不同项目或不同会话中反复出现、并且纠正成本较高的规则才值得固化。偶尔犯一次的错误直接在对话里改掉就好。5.2 版本管理与变更日志模板库本质上是一个代码库它也应该享受代码库该有的待遇git 管理、版本号、变更日志。我现在给模板库的每个文件变更打上语义化版本号并且在 CHANGE LOG 里记录改了什么、为什么改。这样做最大的好处是存量项目不会被新模板的激进改动搞乱。比如v0.3.0 - python 模板新增时区序列化规范 - commands/review.md 增加安全扫描维度 - fastapi 模板增加 alembic check 校验新项目起步时直接使用模板库的最新版本存量项目则保持自己已经生成好的配置不动。除非有重大安全问题我才会主动回旧项目升级配置。正常的功能优化就让新旧项目各用各的版本互不干扰。5.3 几条实战建议最后几条建议都是我在实际使用中一点点磨出来的经验。少即是多。模板的价值不在于完备而在于精准。每加一条规则都要确保它比前面所有规则更接近“不可商量”的级别。我见过有人把模板写成五百行的技术方案文档那基本已经没有约束力了。季度大扫除。每三个月我会把模板库整体过一遍删掉那些没有任何项目在引用的配置块。这个动作的阻力在于每一条规则当初加的时候都觉得自己很需要。但事实是规则一旦没人用就会悄悄腐烂留下也只是误导。让模板跟着仓库走。团队协作的项目配置一定要提交进 git并且从 bootstrap 脚本开始初始化。只有项目级配置入库了模板才是团队的资产而不是某个人的私货。不要迷信万能模板。不同语言、不同框架之间的差异太大一个“适配所有项目”的配置只会变成空洞的套话。组合式的分层模板才是长期可靠的结构。最后说一个我自己的小习惯我每隔一段时间就会故意在一个全新项目里只依赖模板库、不看旧项目的配置直接跑一遍 bootstrap看整个流程会不会卡壳。模板库这种东西长期不用就会悄悄腐烂运行顺畅才是硬道理。