claude-code-templates 这个项目我第一眼看到名字就知道它是干这个的把 Claude Code 里最值钱的东西沉淀成模板。用过 Claude Code 的人都有体会真正费时间的不是装环境、跑命令而是每次开新会话之后上下文里没有你需要的那套规则、风格、流程。你反反复复跟它强调“代码用 strict 模式”“提交信息要按 Conventional Commits 写”“不要动 lockfile”——这些话你说了十遍它下个会话照样忘。claude-code-templates 解决的就是这件事把规则、技能、工作流全部文件化、目录化、可复用让每一次会话都从同一个高起点开始。它适合什么人用一是每天高频使用 Claude Code 写代码的人二是带团队想把 AI 编码规范统一起来的人三是对提示词工程感兴趣、想把技能沉淀成资产的开发者。学习门槛很低只要你会用终端、会看 Markdown 和 JSON基本就能上手。这篇文章我从头到尾拆一遍这类模板库的设计思路、文件结构、核心写法再配合实际踩坑记录和模型接入经验给你一条可以直接抄的落地路径。1. 先搞清楚这个项目到底解决什么问题1.1 为什么 Claude Code 这么需要“模板”Claude Code 这类终端 AI 编程工具本质上是把大模型的能力塞进了一个偏“专家系统”的壳里。它的厉害之处在于能真正读代码、改文件、跑命令但它有一个天然的短板会话是短命的。每次新开对话它对项目的理解归零如果你的项目里有特殊约定就得重新说一遍。你可能会说那我把规则写在第一个 prompt 里不就行了可以但很脆弱。第一prompt 有长度上限规则一多就会挤占真正的任务描述空间第二你没法保证团队里每个人都记得把那段规则粘进去第三规则混在任务里AI 分不清轻重经常跑着跑着就把规则忘了。模板化就是为了解决这些问题把上下文信息拆到独立文件里让 Claude Code 在启动时自动加载而不是靠人肉记忆。1.2 claude-code-templates 的三层沉淀体系这类项目的核心通常包含三层结构claude-code-templates 也不例外规则层就是 CLAUDE.md 文件存放项目全局约定、代码风格、技术栈约束、禁止事项。Claude Code 每次启动会自动读取相当于给 AI 的“入职手册”。技能层Skills 目录下按主题拆分的 Markdown 文件每个文件用 frontmatter 声明名称和触发描述AI 在遇到对应任务时自动翻阅相当于给 AI 的“工作手册”。流程层Workflows 文件把“需求分析→技术方案→编码实现→测试验证→提交前检查”这类多步骤流程固化下来避免 AI 自由发挥导致输出不稳定。这三层各司其职、逐级递进。规则层解决“不能做什么”技能层解决“具体怎么做”流程层解决“按什么顺序做”。把这三层想清楚了模板库的骨架就出来了。2. 搭建自己的模板库目录设计与基础准备2.1 环境准备装好 Claude Code在折腾模板之前先把 Claude Code 装好。它要求 Node.js 18 以上版本官方推荐用 npm 全局安装。装完记得看一眼版本这个细节很关键因为模板库里的某些写法跟版本有关。node -v npm install -g anthropic-ai/claude-code claude --version如果你在 Windows 上推荐优先用 WSL 环境跑我在 Linux 和 WSL 下都实测过稳定性和文件读写速度比在原生 PowerShell 里好不少。macOS 用户直接用终端装就行。装完在任意项目目录执行claude就能进入交互式会话输入/status能看到当前配置信息。注意npm 全局安装目录要加入 PATH。Windows 下常见的问题是 npm 全局包的 bin 目录没有被正确追加导致claude命令找不到安装时留意终端的提示路径。2.2 设计本地模板目录结构Claude Code 的配置读取是有固定位置的用户级配置在~/.claude/项目级配置在项目根目录的.claude/。模板库要做的就是把这套默认配置扩展成一套可复制的结构。我目前用的目录设计长这样claude-code-templates/ ├── CLAUDE.md # 全局规则模板用户级 ├── .claude/ │ ├── CLAUDE.md # 项目级规则模板 │ ├── settings.json # 权限与环境变量 │ ├── skills/ # 技能模板目录 │ │ ├── code-review/ │ │ │ └── SKILL.md │ │ ├── commit-message/ │ │ │ └── SKILL.md │ │ └── refactor/ │ │ └── SKILL.md │ ├── workflows/ # 工作流模板目录 │ │ └── feature-development.json │ └── commands/ # 自定义斜杠命令 │ └── review.md └── templates/ # 按场景区分的完整模板 ├── frontend-react/ ├── backend-node/ └── python-service/这套结构的核心思想是“通用规则放上层场景化模板按下层”。CLAUDE.md是启动时自动加载的所以只放所有项目都适用的内容项目特定的规则单独放一层用的时候整体拷进目标项目就行。分层的收益在于你维护一个模板库团队里每个人拿到手就是一套完整的、口径一致的 AI 工作环境不会出现“每个人各写各的规则”这种混乱。2.3 用 Git 管理模板版本既然是模板库就一定要纳入版本管理。我踩过最大的坑是“改了一版 CLAUDE.md忘了哪个项目用的老版本结果 AI 行为诡异”。后来我强制自己按 tag 发版项目初始化时锁定某个 tagcd my-project git clone template-repo .claude-templates cp -r .claude-templates/.claude/* .claude/模板更新后只需要git pull拉新版本再手动 review 一遍 diff 就行。模板库的 changelog 特别重要——每一行规则变化都会影响 AI 在所有项目里的行为升级前一定要看清楚改了什么。3. 模板的核心载体CLAUDE.md 怎么写才有效3.1 全局、项目、子目录三级优先级CLAUDE.md 的加载规则是层层覆盖的这也是模板库设计的根基。Claude Code 会读取三个位置的 CLAUDE.md按优先级从高到低排列项目根目录的./CLAUDE.md用户目录的~/.claude/CLAUDE.md当前子目录下的.claude/CLAUDE.md注意子目录的优先级最高。这不难理解离当前工作目录最近的文件对 AI 的影响最直接。模板库的策略是全局文件只放通用价值观和红线比如“不私自删除文件”“不改 lockfile”项目文件放具体技术栈和编码规范子目录文件放模块专属约束。三层各司其职不互相覆盖。很多人的模板文件写不好就是因为把项目特定内容和通用内容混在一起。全局规则一改所有项目都受影响导致某个项目里 AI 的行为突然变怪——八成就是你改了全局层却没注意项目层是否覆盖。3.2 一份可以直接抄的通用 CLAUDE.md这里给一份我实测下来效果不错的通用模板不需要全部照搬按需剪裁# 项目编码规则 ## 代码风格 - TypeScript 项目统一启用 strict 模式 - React 组件文件使用 PascalCase工具函数使用 camelCase - 所有导出函数必须附带 JSDoc 注释 - CSS 类名统一使用 BEM 命名法 ## 技术栈 - 前端React 18 Vite 5 TypeScript - 后端Node.js 20 Fastify - 数据库PostgreSQL Drizzle ORM ## 通用约束 - 不要修改 package-lock.json除非新增或更新依赖 - 测试命令是 npm run test不接受其他替代入口 - 提交信息遵循 Conventional Commits 规范 ## 禁止事项 - 禁止格式化不属于本次任务的代码 - 禁止在未咨询用户的情况下执行破坏性命令 - 禁止使用已废弃的 API 或第三方库这份模板的核心在于“明确 可验证”。我给每条规则都想好了 AI 怎么判断是否违反比如“锁定文件只在更新依赖时修改”AI 一看到npm install命令就能关联到这条规则。太抽象的描述比如“写出高质量的代码”AI 根本不知道怎么执行等于没写。3.3 写 CLAUDE.md 的三个禁忌第一条千万不要太长。CLAUDE.md 每次启动都会加载占用的都是上下文窗口。我见过有人把几百行规范全塞进去结果 AI 反而抓不住重点行为变得比没有规则时更不稳定。控制篇幅的标准是一条规则如果不能在 20 个字以内说清楚大概率是没想明白。第二条不要写“正确的废话”。“保证代码质量”“注意安全”这种话不写也罢AI 本身就会这么做。模板要写的是“在这个项目里特殊的事”比如“用 pnpm 不用 npm”“测试必须用 vitest 不用 jest”越具体越有约束力。第三条避免规则之间相互冲突。比如一条规则说“优先使用现有组件”另一条又说“禁止修改现有组件”AI 会陷入两难表现就是行为随机。每条规则写完后检查一遍有没有跟其他规则打架。4. Skills 与 Workflows把高频操作变成可复用技能4.1 Skills 的本质Markdown frontmatter 可选脚本Skills 是 Claude Code 里“按需触发”的知识块。它跟 CLAUDE.md 的区别是CLAUDE.md 每次加载Skills 只在你提到相关任务时才被 AI 翻阅。这种设计避免了主上下文的浪费同时把专业知识拆成小块方便独立维护。一个标准的 Skill 目录长这样skill-name/ ├── SKILL.md # 技能描述 └── scripts/ # 可选的辅助脚本SKILL.md 的 frontmatter 里必须有name和description。description是 AI 决定“要不要读这个技能”的依据所以一定要写清楚“什么时候触发”。我见过不少人栽在这里描述写得太宽泛AI 什么都触发根本起不到分流作用。4.2 写一个代码审查 Skill 模板代码审查是我日常用得最频繁的技能直接放一个模板--- name: code-review description: 在用户要求审查代码、检查 MR、review 变更时使用。用于逐文件审查代码变更输出风险清单与改进建议。 --- 你是一名资深代码审查专家。按以下步骤执行 1. 先运行 git diff --stat 查看变更文件列表 2. 对每个变更文件 - 先看产出物组件、接口是否正确处理了边界条件 - 检查是否遵循项目 CLAUDE.md 中的编码风格 - 关注潜在的性能问题不必要的渲染、重复请求、内存泄漏 3. 输出审查结论格式 - 必须修改chevere 严重问题 - 建议修改非阻塞但值得改进 - 可选建议风格层面的优化空间 注意只审查变更行不要对未改动的代码指手画脚。这个模板的精华在最后一行“只审查变更行”。没有这条约束AI 经常会把整个文件的老代码拿来说事输出一堆没用的建议审查报告完全偏离重点。这就是模板里“避坑经验”的价值——你不会在官方文档里看到这种细节都是用的次数多了才总结出来的。4.3 Workflows把多步骤任务编排成固定流程Workflows 适合那种“每次做都容易漏步骤”的任务。我举个例子标准化功能开发流程如果每次让 AI 自由发挥它经常跳步骤方案还没确认就开写测试没跑完就提交。用 workflow 可以把过程固定下来。.claude/workflows/feature-development.json{ name: feature-development, description: 标准功能开发工作流适用于新功能模块的设计与实现, steps: [ { role: planner, task: 阅读需求输出技术方案包括涉及的模块、接口变更、数据模型变化 }, { role: implementer, task: 按已确认的技术方案实现代码使用项目 CLAUDE.md 中的编码规范 }, { role: tester, task: 补充或更新测试用例执行测试命令并修复失败项 }, { role: reviewer, task: 对照需求清单逐条验证输出未完成项和风险项 } ] }使用的时候在会话里输入/workflows feature-developmentAI 就会按步骤执行。它带来的最大价值是可预期性同一个人在不同时间跑同一个 workflow产出的流程结构基本一致不会这次漏了测试、下次漏了方案评审。4.4 自定义斜杠命令更轻量的模板形态有时候为一个小场景单独建 workflow 显得重可以用自定义命令顶替。.claude/commands/review.md里写请对当前分支的变更执行一次快速代码审查。 重点检查错误处理、边界条件、与现有设计的一致性。 输出格式按严重程度分级的清单。这样在会话里直接/review就能触发。命令是介于“纯 prompt”和“完整 workflow”之间的形态适合频繁使用但不需要多步骤编排的场景。5. 模型接入与运行调优模板库的真正威力5.1 把 Claude Code 接到 DeepSeek我自己日常主力用的是 DeepSeek 的模型不是因为哪个更好而是这样跑批量任务成本压力小很多。Claude Code 通过环境变量和配置项支持替换 API 端点社区里把这套配置戏称“接入第三方兼容接口”。做这件事之前要明白Claude Code 本身支持通过ANTHROPIC_BASE_URL指向任何兼容 Anthropic API 格式的服务端所以接入的关键就三个环境变量接口地址、认证令牌、模型名。配置写在settings.json里即可{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: sk-你的密钥写这里, ANTHROPIC_MODEL: deepseek-chat, ENABLE_PROMPT_CACHING_1H: 1 }, permissions: { allow: [Bash, Read, Edit] } }这里有几个细节值得展开ANTHROPIC_MODEL不一定要设置取决于兼容服务端是否有自己的默认模型选择逻辑。如果你发现输出的模型不是你预期的那一个再显式设置这个变量。ENABLE_PROMPT_CACHING_1H这个配置有没有用实测下来如果服务端支持 prompt caching确实能降低长上下文会话的费用如果服务端不支持缓存这个配置也不会报错只是不生效。建议开着。permissions.allow这段我建议写上否则 AI 每次执行命令都要弹确认模板库跑到一半卡住等你点头体验很差。5.2 用 cc-switch 管理多套模型配置热词里出现过的 cc-switch我实际装了之后发现它就是针对 Claude Code 这类工具的多配置管理器。它的作用可以用一句话概括把“改环境变量→重启会话”这个过程自动化。安装方式很简单直接从它仓库的 Release 页下载对应平台的安装包。装完后的使用逻辑是每个配置项里绑定一个 API 端点、密钥、模型名、可选的自定义 header切换模型时一键切换。我同时维护了 4 套配置官方 Claude 模型、DeepSeek 兼容接口、本地部署的推理服务、团队协作共享的网关服务。写模板库的时候我特意把“模型无关”作为一条原则——同一个 workflow 跑不同的模型效果对比才有意义。经验之谈如果你频繁切换模型建议在会话开头顺手/status看一眼当前生效的配置防止上次切完模型忘了切回来导致批量任务跑在非预期的模型上浪费时间和 token。5.3 正确使用思考等级和上下文缓存Claude Code 里有个思考等级的设置热词里的 “xhigh” 指的就是最高档。命令是/think high、/think xhigh这种形式或者通过快捷键调整。放在模板库的语境下我的建议是日常开发的默认思考等级用medium速度快、响应稳定做架构设计、复杂调试、代码审查时临时调到high或xhigh把“什么时候用什么等级”写进模板而不是让使用者凭感觉调。上下文缓存这块主要关注ENABLE_PROMPT_CACHING_1H和ENABLE_PROMPT_CACHING_5M这两个变量。在长会话中如果能命中缓存响应速度快了不止一点点。模板库里第一次跑任务时可以加一行“确认缓存是否生效”实现方式就是问 AI “你当前的系统提示词是从缓存加载的吗”或者直接看 API 的 usage 统计。5.4 模板库、模型、对话三板斧的配合逻辑拆个真实的例子我同时维护一个前端项目和后端项目共用一个全局 CLAUDE.md里面只有两条规则遵守 Conventional Commits、不删除用户文件后端项目有自己的 CLAUDE.md数据库操作、缓存策略前端项目也有自己的 CLAUDE.md组件规范、样式方案。跑功能开发时两边都能套用同一个 workflow但在技能调用上会各自命中对应模块的技能。这就是模板库和模型接入配合起来最大的价值写代码的“环境”和写代码的“大脑”解耦了。你换模型不用换规则你换项目也不用换模型。一个人维护一套模板库多个项目、多套模型都能跑得顺畅。6. 实战记录从初始化模板库到完成一个完整任务6.1 完整流程实录我最近用一个新项目做了一次从零初始化完整体验了一遍模板库的流程。第一步是搭目录骨架mkdir my-project cd my-project git init mkdir -p .claude/skills .claude/workflows .claude/commands touch CLAUDE.md npm init -y然后从模板库拷贝规则和技能文件到对应目录再手工 review 一遍把项目特定的技术栈信息填进 CLAUDE.md。这里有个容易被忽略的点模板库里的规则默认是“通配”的比如我模板里写了“TypeScript 严格模式”但新项目是 Python拷贝完必须改掉否则 AI 会按错误的规范输出代码。改完后启动会话验证效果claude然后直接问一句“请总结这个项目的技术栈和编码规范”如果 AI 能准确说出 CLAUDE.md 里的内容说明规则加载成功。再试/review命令看自定义命令是否注册成功。这套验证流程建议每次初始化新项目都跑一遍别等到任务跑了一半才发现规则没生效。6.2 我在实际使用中遇到的几个典型问题问题一突然出现区域可用性提示有段时间我在某台服务器上启动 Claude Code 时会话里弹出了“might not be available in your country”之类的提示。这个实际上是因为当前配置的模型端点或密钥不被认可时Claude Code 做兼容性提示。我当时排查的路径是先看ANTHROPIC_BASE_URL是不是指向了我预期的服务端再看密钥有没有过期最后检查模型名是否被目标服务端支持。逐个排除后发现是我存密钥的方式有问题——环境变量里带了个换行符导致认证失败。换成干净的密钥后问题消失。排查这类问题核心思路是“剥离层”先把环境变量全部清掉只留最基础的配置确认能通之后再加自定义项。不要在一个复杂配置上瞎猜效率太低了。问题二会话卡在 tool use 等待响应跑 workflow 时 AI 执行到某一步会卡住不报错也不继续。我后来发现是 workflow 步骤里写了一句模糊的指令让 AI 在“等待用户确认”的逻辑上绕进去了。解决办法是把 workflow 步骤写得更具指令性明确什么时候可以继续、什么时候必须停下询问用户。模板库里的 workflow 写完后一定要自己跑一遍真实任务验证光看 JSON 格式正确是不够的。问题三settings.json 权限配置没有生效我一开始写模板库时把权限配置只放在项目级 settings.json 里但会话内跑命令还是疯狂弹确认。后面发现项目级 settings.json 确实有权限配置的写法要求得写对字段名和值格式而且有些权限请求比如写文件需要单独声明。最稳妥的验证方式是在会话里执行一次需要权限的操作观察是否弹出确认不弹就说明配置生效。弹出确认时的按钮文案也会提示是受哪个配置影响逐条对齐就好。问题四SDK 报错版本不匹配热词里的“claude code sdk下载”对应的场景是这样的模板库里的某个技能脚本依赖了 Claude Code SDK 的某个接口但 SDK 版本更新后接口签名变了脚本直接报错。我后来在模板库里给技能脚本补了版本声明并且不锁死依赖只声明最低版本避免后续的小版本升级导致完全不兼容。这个问题的通用解法是“模板库里的脚本尽量少依赖 SDK 的未稳定接口”能用子进程调用 CLI 就用子进程稳定性好得多。6.3 问题排查速查表症状常见原因排查顺序会话启动提示区域可用性模型端点/密钥不受支持1. 检查 BASE_URL 2. 检查密钥 3. 检查模型名命令执行频繁弹确认权限配置未生效1. 检查 settings.json 字段 2. 检查已授权列表会话卡在等待状态workflow 指令模糊1. 检查步骤描述 2. 加“继续”条件技能脚本报错SDK 版本不匹配1. 看报错行 2. 查接口变更 3. 改用子进程规则没有生效CLAUDE.md 加载路径不对1. 检查文件位置 2. 重启会话 3. 用 /status 确认模型响应风格不一致切换配置后未重启会话1. /status 查看 2. 重启会话再跑这个表是我这几个月的真实记录不管是不是 claude-code-templates 这个仓库的直接使用者只要是 Claude Code 玩家大概率都会碰到其中几条。7. 维护模板库半年后我想分享的几条经验最后聊几句我自己折腾下来的体会不算系统总结就是真实感受。第一条模板库最大的敌人是“过度设计”。我早期追求把所有东西都模板化结果维护成本比收益还高很多规则写了三个月没用过一次内容越来越臃肿。后来我定了原则同一个技能如果一个月没用上三次就考虑从模板库里删掉同一个工作流如果跑起来不顺畅就果断改掉不要心疼。模板库要像代码库一样敢于重构。第二条如果你要把模板库分享给团队用一定记住“配置要做好默认值”。不要让同事手动改一堆环境变量。我见过很多团队想统一 AI 编码规范结果规范文件写得挺漂亮但同事用的时候一堆配置问题最后还是各用各的。模板库的落地百分之八十的工作量在降低使用门槛上。第三条模板库给了 AI 一个稳定的“工作记忆”但它也反过来约束了你。你写进 CLAUDE.md 的每条规则都会影响 AI 在所有项目中的行为边界。这个边界不是越细越好而是越稳越好——让 AI 知道自己能做什么、不能做什么、做完之后要输出什么。一套稳定的规则体系比更聪明的模型更能提升长期产出质量。如果你现在还在靠人肉重复给 Claude Code 打招呼式地交代背景信息强烈建议花半天时间把 claude-code-templates 这类项目拆一份下来按自己的习惯重新组装。装完之后你会发现AI 编程终于是个工程化的事了。