我第一次把前一个项目的CLAUDE.md原封不动复制到新项目的时候发现这个新项目用的完全是另一套技术栈、另一套构建工具、另一套团队规范结果 AI 满嘴跑火车式地按旧规矩给我“优化”代码气得我当场把文件删了。从那天起我就意识到Claude Code 的模板不是说你攒一个文件然后到处复制它应该是一套可以按需组合的积木项目规则、斜杠命令、钩子脚本、技能文件、脚手架脚本每一层管一件事组合起来才是真正好用的claude-code-templates。这篇文章把我自己沉淀了大半年的模板体系完整拆给你看。我默认你已经在用 Claude Code至少知道claude命令能在终端里跑起来知道它会把对话上下文发给模型。至于模板怎么设计、怎么落盘、怎么排错我会全部展开讲。内容适用于独立开发者也适用于团队协作场景拿来改一改就能直接进你的仓库。1. 先弄清楚模板到底在“套”什么东西1.1 我说的模板不是你想的那个模板大部分人听到“模板”两个字第一反应是 UI 层面的东西比如生成一份 Markdown 文件、生成一个 React 组件。但 Claude Code 是终端里的 AI 编程助手它的“模板”概念要宽得多。我把它拆成四层上下文模板也就是CLAUDE.md告诉 Claude“这个项目是什么、有什么规矩、哪些东西不能碰”。命令模板放在.claude/commands/下的斜杠命令相当于给 AI 预置好的“动作脚本”输入/review就执行一套完整的代码审查流程。钩子模板挂在settings.json里的自动触发脚本拦截特定事件比如“AI 准备执行 Bash 命令前先检查一遍”。技能模板也就是 Agent Skills以 Markdown 文件组织的可复用方法论让 Claude 在遇到相关任务时自动加载对应的操作手册。这四层各管一摊彼此又耦合。上下文模板打底命令模板管一次性动作钩子模板管纪律技能模板管方法论。把它们组合成一个目录结构再交给 git 管理这就是你个人的claude-code-templates。1.2 模板体系要解决的三个实际问题我在没有模板体系之前每天在终端里重复劳动。第一个问题是每次开新对话都要重新解释项目背景明明上一个会话已经聊清楚了换个目录又是从零开始第二个问题是项目规则靠嘴说AI 听完就忘今天遵守明天不遵守第三个问题是团队的代码规范在 Claude Code 这里根本没有落到实处的通道Review 不严、测试不跑、提交信息乱写。模板体系就是冲着这三个问题去的。CLAUDE.md解决“每次都要重复解释”的问题命令模板解决“动作流程不可复用”的问题钩子解决“规则只靠自觉”的问题技能解决“团队方法论没法沉淀”的问题。一套模板建好之后你在一台新机器上拉下仓库装好 Claude Code几秒钟就能得到和原来完全一致的 AI 协作环境。我一直强调一个观点模板不是给 Claude 看的是给你的工程流程看的。Claude 只是一个执行体你在模板里写清楚流程它的输出质量才能稳定在及格线以上。这个过程本身就是在给 AI 编程这件事做“配置管理”。2. 第一层CLAUDE.md——把项目语境变成可复制的文件2.1 CLAUDE.md 到底该怎么写很多人以为CLAUDE.md写得越多越好恨不得把整个 wiki 灌进去。我在早期也犯过这个错写了两千多行结果 Claude 反而抓不住重点经常被无关细节带偏。后来我总结出一个判断标准CLAUDE.md里的每一句话都应该能直接影响 AI 的行为决策。不能影响决策的垃圾信息全部拿出去。一份合格的CLAUDE.md应该包含这五块内容项目身份一句话说清这个项目是干什么的技术栈是什么仓库结构长什么样。核心命令开发、构建、测试、检查这些常用命令分别是什么。AI 一旦知道怎么跑测试它就会在改完代码后主动跑一遍。编码规范缩进、命名、组件边界、状态管理方式等硬性约定。禁区条款哪些依赖不能引入哪些目录不能修改哪些模式已经被淘汰。禁区比建议更重要AI 非常擅长在你不注意的时候偷偷引入新依赖。当前工作流目前团队在用什么模型、什么部署流程、什么测试策略。这个部分需要随项目迭代而更新。开头那段“项目身份”一定要精炼。我见过有人写十行Claude 也没理解到底谁是谁。我用的是一个很粗暴的做法一句话说“这是一个面向 XXX 场景的 XXX 服务主要技术栈是 XXX”然后给一段目录结构示意再给两三行“这里的关键模块是 XXX”。这样即使是一个从未见过这个仓库的 AI也能在第一次交互时就建立基本空间感。2.2 一套可以抄的通用 CLAUDE.md 模板下面这个模板我几乎在每个新项目里都会先铺一层然后再按项目特性增删。你直接复制到项目根目录把方括号里的内容换成自己的就行。# CLAUDE.md ## 项目身份 - 一句话这是一个 [项目类型] 主要解决 [核心问题]。 - 技术栈[语言] [框架] [数据库/缓存等]。 - 仓库结构 - apps/web 前端应用 - apps/api 后端服务 - packages/shared 共享代码 ## 常用命令 - 安装依赖pnpm install - 本地开发pnpm dev - 运行测试pnpm test - 代码检查pnpm lint - 类型检查pnpm typecheck - 构建pnpm build ## 编码规范 - 使用 TypeScript strict 模式。 - 组件使用函数式写法禁止使用 class 组件。 - 状态管理统一使用 [zustand / pinia / vuex]不要自造状态容器。 - 样式使用 [CSS Modules / Tailwind / 样式组件]。 - 提交信息遵循 conventional commits 格式。 ## 禁区 - 不要引入 [某个已经被否决的库]改用 [替代方案]。 - 不要直接修改 packages/shared 中已被标记为 frozen 的 API。 - 不要为单测构造复杂 mock优先使用真实依赖做集成测试。 ## 当前工作流 - 主分支main发布流程PR 合入后自动触发部署。 - CI 中必须通过 lint、typecheck 和 test否则不能合入。 - 数据库迁移由专门的迁移脚本管理禁止手工改库。这份模板的关键在于“命令优先”。Claude 最终要落到执行上如果它连测试命令是什么都得猜效率一定低。你可以把常用命令放在最显眼的位置甚至重复出现两次都没关系只要它能在需要的时候快速检索到。2.3 我踩过的“规则打架”坑写了半年CLAUDE.md我最深刻的教训是“规则会打架”。举个真实的例子我在一个项目里写了“优先使用现有的工具函数”又在另一个项目里写了“禁止使用全局工具函数必须在模块内实现”。结果两个规则分别被不同子任务触发AI 经常一边说“按全局规范来”一边实现了一套完全相反的做法。后来我学乖了。所有进入CLAUDE.md的规则必须先做一次一致性检查问自己一个问题这条规则和现有的哪条规则可能冲突一旦发现两条规则指向不同的行为方向要么删掉一条要么加上明确的适用边界。另外我还会在末尾加一个“规则优先级”小节明确写“当规则冲突时越靠前的规则优先”。这样就算漏了一条矛盾语句AI 也有一套自己的仲裁逻辑。还有一个容易踩的坑是不要在CLAUDE.md里放“希望型”语句。比如“代码质量尽量高一点”这种话AI 无法把它变成可执行动作。它应该被翻译成“所有新增函数必须包含 JSDoc 注释”“单测覆盖率不能低于 80%”这种可检查、可验证的硬性条件。3. 第二层斜杠命令——把高频操作沉淀成指令模板3.1 命令模板的存放规则Claude Code 的自定义斜杠命令放在两个位置用户级的~/.claude/commands/和项目级的.claude/commands/。用户级适合放通用的、工作流相关的命令比如“写周报”“解释这段代码”项目级适合放和当前仓库强相关的命令比如“运行这个项目的测试”“按本项目的规范新增加接口”。文件的命名决定了命令名。你创建.claude/commands/review.md之后在 Claude Code 对话框里输入/review就能触发这个模板。文件里的内容会作为提示词注入当前对话相当于你替 Claude 写好了一整套审查指令。我强烈建议所有团队成员都使用项目级命令目录。这样不管谁在哪个分支上工作执行同一个/review命令得到的行为是一致的。如果放在个人级目录里每个人存的文件内容都不一样执行效果当然就五花八门。3.2 实战命令模板代码审查、测试、加接口我给你三个最常用的命令模板作参考。第一个是/review代码审查命令。它的一般形态是这样--- description: 审查当前分支的代码变更输出问题和修改建议 --- 你是一名资深代码审查者。请按以下步骤开展审查 1. 先执行 git diff main...HEAD --stat 查看变更概览。 2. 再执行 git diff main...HEAD 获取逐行差异。 3. 逐个文件分析重点关注 - 逻辑错误和边界情况 - 性能隐患不必要的循环、重复计算、内存泄漏 - 安全风险注入、越权访问、敏感信息泄露 - 与项目规范的偏差 4. 输出格式 - **严重问题**必须修复后才能合入 - **建议改进**不影响合入但应当关注 - **亮点**写得好的地方给点正向反馈 注意如果差异太大先向用户确认审查范围不要一次灌入超过 2000 行代码。这个模板做对了三件事先看概览再看细节避免 AI 一上来就被淹没把审查目标写成可检查的清单而不是一句“帮我看看代码”最后加了一个“差异太大先确认范围”的保护条款防止长分支把上下文撑爆。第二个是/add-test为指定文件补测试的命令模板--- description: 为指定模块补充单元测试 --- 请为 {{file_path}} 文件中的核心逻辑编写单元测试。 要求 1. 先读取原文件梳理公开函数和边界场景。 2. 测试文件放在与源文件同级的 __tests__ 目录。 3. 覆盖以下场景正常输入、空输入、异常输入、依赖不可用。 4. 使用项目已有的测试框架和 mock 方式。 5. 写完测试后运行对应命令确认全部通过。 如果原文件没有可测试逻辑直接说明原因并给出重构建议。这个模板充分利用了{{file_path}}这个占位变量AI 会自动读取你在对话里选中的文件路径。这样就不用每次手写一遍“哪个文件”效率高很多。第三个是/new-api按项目规范新增一个接口。这个模板和项目强相关因为不同项目的接口规范完全不同--- description: 新增后端 API 接口 --- 请实现一个新的 API 接口。 步骤 1. 确认已有的路由注册方式参考 apps/api/src/routes/ 下的现有模块。 2. 在对应模块中新增路由和处理函数。 3. 补充入参校验校验规则参考项目现有的 zod 定义。 4. 更新 OpenAPI 文档。 5. 新增对应的集成测试。 6. 运行 pnpm typecheck pnpm test 确认无回归。 注意不要引入新的 HTTP 框架不要绕过现有鉴权中间件。3.3 让命令模板接受参数的技巧命令模板里能用的占位符比我想象中灵活。{{file_path}}会自动绑定当前选中的文件{{file_content}}会带着文件内容一起进来。你还可以在模板里写普通变量比如{{module_name}}AI 会结合上下文尝试推断。不过我的经验是占位符别太贪多一个模板最多两三个变量就够了否则 AI 大概率会为了凑变量而胡编。更实用的技巧是利用 Bash 命令动态注入信息。比如在模板里写当前分支$(git branch --show-current) 最近提交$(git log --oneline -5)AI 执行命令后就能拿到实时信息比我们在模板里手动维护状态要可靠得多。这招在写周报、写发布说明、做审查时特别管用。4. 第三层Hooks——把纪律做成自动化的钩子4.1 钩子能拦住哪些“手滑”Claude Code 的钩子机制允许你在 AI 生命周期的关键节点挂上自己的脚本。和命令模板的“人类主动触发”不同钩子是被动触发、自动执行的适合用来做纪律性拦截。我实际用到最多的三个场景是PreToolUse 拦截AI 准备执行某个 Bash 命令之前先检查命令内容。比如我写过一段脚本禁止 AI 在生产环境目录里直接执行rm -rf一旦匹配到高危命令就中断执行。PostToolUse 检查AI 执行完某个工具之后脚本可以读取输出并判断结果。比如每次 Edit 操作结束之后自动跑一遍格式化确保代码风格统一。Stop 钩子收尾AI 回复用户之前触发。我在这里挂了一个小脚本检查当前是否有未解决的 lint 错误如果有就在回答里附加一句警告。钩子的设计原则是“小、快、专一”。一个钩子只做一件事脚本尽量短不要在里面写复杂业务逻辑。因为钩子会在 AI 的每次操作中被反复触发一旦脚本卡住或者抛异常整个会话都会受影响。4.2 一套安全的 hooks 配置长什么样这里给你看一份简化版的settings.json配置文件位于项目根目录的.claude/settings.json{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: sh .claude/hooks/guard-danger-commands.sh } ] } ], PostToolUse: [ { matcher: Edit, hooks: [ { type: command, command: sh .claude/hooks/auto-format.sh } ] } ], Stop: [ { hooks: [ { type: command, command: sh .claude/hooks/check-pending-todos.sh } ] } ] } }对应的guard-danger-commands.sh可以写成这样#!/usr/bin/env bash input$1 dangerous_patterns(rm -rf / DROP TABLE git push --force) for pattern in ${dangerous_patterns[]}; do if echo $input | grep -q $pattern; then echo blocked: 检测到高危命令 $pattern已阻止执行。 exit 2 fi done exit 0钩子通过标准输入接收 JSON 格式的事件数据第一个参数是事件 JSON所以脚本里读取$1能拿到具体命令内容。exit 0表示放行exit 2表示阻止。我用这个号区分业务逻辑错误和人为拦截调试起来更容易定位问题。4.3 编辑 hooks 时的调试方法钩子脚本有个让人头大的特点它是静默失败的。AI 在终端里命令执行失败还能看到红色的报错但钩子脚本如果出问题可能只是日志里多了一行hook failed不影响主流程。所以我在开发钩子阶段会特意让脚本输出大量调试信息。最实用的做法是先在终端里手动跑一遍钩子脚本把事件 JSON 存成文件再用它当输入来调脚本。比如# 把真实事件 JSON 存下来 cat $(claude hooks debug-event PreToolUse) /tmp/event.json # 直接用这个文件测试脚本 sh .claude/hooks/guard-danger-commands.sh /tmp/event.json这样每次改脚本不需要重新启动 Claude Code直接循环调脚本后再测试。等你确认稳定了再去掉多余的调试输出。另一个经验是钩子脚本不要用太新潮的语法特性。Claude Code 的钩子最终是在本机 shell 里跑的不同机器上的 bash 版本差距巨大。我统一用最基础的 POSIX 语法写脚本规避掉一群“在我电脑上明明是好的”问题。5. 第四层Agent Skills——把团队方法论喂给 AI5.1 Skill 模板的基本结构Agent Skills 是 Claude Code 里相对较新的能力。它本质上是一组 Markdown 文件放在.claude/skills/skill-name/目录下每一个 Skill 目录里必须有一个SKILL.md作为入口。SKILL.md的头部需要 YAML frontmatter里面至少要有name和description。description非常关键因为它是 AI 判断“什么时候该加载这个 Skill”的依据。如果你的描述里包含了触发场景的高频词AI 就更可能在相关任务发生时主动加载这个 Skill。一个典型的 Skill 文件结构长这样--- name: dependency-audit description: Review package dependencies for security, duplication, and architecture fit. Use when analyzing package.json or dependency-related issues. --- # Dependency Audit ## 背景 本技能用于检查一个 Node.js 项目的依赖健康状况。 ## 执行步骤 1. 读取 package.json列出顶层依赖清单。 2. 检查重复依赖确认是否存在同一功能的不同库。 3. 识别长期未更新的依赖评估升级风险。 4. 检查是否有已被标注为 deprecated 的包。 5. 输出一份 dependencies 风险报告按严重程度排序。 ## 判断标准 - 同一个核心功能出现两个以上库时给出合并建议。 - 依赖版本落后主版本超过 3 年时标记为高风险。 - 框架级别的依赖必须与项目主体技术栈保持一致。5.2 我推荐的三个轻量 SkillSkill 这种东西做多了容易变成知识库垃圾场。我目前长期维护的只有三个轻量 Skill效果比维护二十个强得多。第一个是codebase-guide。它存储的是“如何阅读这个项目的代码”的方法论比如“先看哪个文件夹”“核心链路在哪个模块”“什么时候该看 OpenAPI 文档”。表面上是给 AI 的导航实际上是在把团队新人的 onboarding 手册翻译成 AI 能读的格式。第二个是test-writer。它存的是这个团队写测试的风格约定比如“测试命名规范”“mock 偏好”“集成测试和单测的边界”。AI 加载这个 Skill 之后再写测试就不再出现“测了一个没用函数”或者“mock 了不该 mock 的依赖”这种尴尬情况。第三个是error-diagnosis。它是一套排查报错的固定流程先复现再缩小范围分开检查代码和配置最后看系统日志。这个方法论听起来很简单但对 AI 特别有用。没有这套流程时AI 面对一个报错经常东猜一下西猜一下加载 Skill 之后就会老老实实按步骤走反而更快能定位到问题。5.3 Skills 和命令模板怎么分工这是我被问得最多的区分问题。命令模板是“人主动触发的一次性动作”技能是“AI 根据场景自动选择的方法论”。同样是做代码审查/review命令适合你主动喊一句“给我审查一下最近改动”而code-review-guideSkill 适合在 AI 日常修改代码的过程中自动遵守一套审查标准。所以我的建议很直接如果某个流程是你要主动执行的做成命令模板。如果某个流程希望 AI 在背后一直遵守做成 Skill。两者可以配套使用比如命令模板里注明“请先加载某 Skill”AI 就会在触发命令时把对应的技能文件一并纳入上下文。6. 第五层脚手架——让新项目五秒启动6.1 最小可用目录结构四层模板本身已经很能打了但要让“整套体系”真正落地到新项目还差最后一步脚手架。我维护了一个claude-code-templates仓库里面保存了一套完整的模板骨架新建项目时直接复制进去就行。最小的目录结构长这样project/ ├── CLAUDE.md └── .claude/ ├── settings.json ├── commands/ │ ├── review.md │ ├── add-test.md │ └── new-api.md ├── hooks/ │ ├── guard-danger-commands.sh │ ├── auto-format.sh │ └── check-pending-todos.sh └── skills/ ├── codebase-guide/SKILL.md ├── test-writer/SKILL.md └── error-diagnosis/SKILL.md这个结构一小部分我直接用上一份项目的大部分是最近整理出来的子类。我试过把整个模板库硬拷到仓库里结果每次项目迭代都要同步主仓库累死。现在改成“按需复制 模板仓库版本管理”的组合策略舒服多了。6.2 应用脚手架的自动化脚本手工复制多了还是会烦所以我在模板仓库里放了一个bootstrap.sh用它一键初始化。核心逻辑很简单复制目录、替换占位符、根据交互输入写入项目名和技术栈。脚本片段示意#!/usr/bin/env bash set -euo pipefail template_dir$(dirname $0)/template target_dir${1:?Usage: bootstrap.sh target-dir} cp -r $template_dir/. $target_dir/ cd $target_dir # 替换项目名占位符 sed -i s/__PROJECT_NAME__/$project_name/g CLAUDE.md # 根据技术栈选择性的保留命令模板 if [[ $stack node ]]; then mv .claude/commands/new-node-service.md .claude/commands/new-api.md fi rm .claude/commands/__unused__.md我刻意让脚本保持简单。有些人喜欢用交互式引導但我追求的是“新环境里一分钟跑完而且每一条命令都看得懂”。一旦脚本复杂到需要调试就违背了脚手架工具的本意。6.3 分发和团队同步模板仓库本身也扔在 git 里这个不用多说。团队协作时有两种同步方式。第一种是直接复制适合模板还不稳定、团队规模小于五人的时候第二种是用 git submodule 或者 subtree 挂到各项目里适合模板已经稳定、且多个项目需要共用时。我想强调一个细节模板仓库里的任何修改都不会自动同步到已经复制出去的项目里。所以团队里要有一个明确的“模板更新流程”。我的做法是每季度抽出半天把各项目中已经跑通的改进合并回模板仓库反向把模板仓库的更新公告发到团队频道。这个过程虽然手动但它能强制大家思考“这条规则真的适合所有项目吗”不至于把特别个性化的规则硬化成全公司模板。7. 实战排错与避坑笔记7.1 常见问题速查表我把这一年来最常遇到的问题整理成一份速查表大家可以直接对着查。现象可能原因解决方案命令模板没有生效文件放错目录或文件名不是斜杠命令名检查.claude/commands/下文件名与触发命令是否一致CLAUDE.md 被完全忽略规则太抽象或与其他规则冲突把规则改成可验证的硬条件检查冲突并加上优先级说明钩子脚本没跑settings.json格式错误用claude hooks debug直接输出事件 JSON 验证钩子脚本报错但不影响主流程脚本中的命令在非 bash 环境不可用统一改用 POSIX 兼容语法避免 bash 专属特性Skill 从未被自动加载description里的触发词太少加入常见场景的核心关键词优化触发命中率模板仓库同步混乱各项目直接复制导致分叉改用 submodule制定定期回滚流程加了钩子后 AI 变慢明显钩子脚本执行耗时过长精简脚本逻辑只在关键匹配处做判断这些问题绝大多数不是 Claude Code 本身的问题而是我们作为使用者的工程习惯问题。模板体系本质上也是一套工程系统排错思路和调试后端服务没什么两样——先确认配置加载了没有再确认输入输出是否符合预期最后才查业务逻辑。7.2 那些文档不会告诉你的小细节经验里还有几个细节十分隐蔽这里一并记录下来。第一个是命令模板里尽量不要写死超长常量。把一大段 JSON 直接塞在命令模板里会导致每次触发时上下文被瞬间占满后续对话的质量明显下降。我的做法是把长内容放进单独的文件命令里只写“参考.claude/context/api-rules.md中的定义”让 AI 按需读取而不是一次性把全部内容灌进上下文。第二个是CLAUDE.md并不是只会读根目录的那个。Claude Code 会从当前工作目录向上逐级寻找CLAUDE.md也会识别子目录中的同名文件。利用这个机制我经常把大的规则拆成两层根目录放全局约束子模块目录放局部约束。比如apps/web/CLAUDE.md只讲前端特有的事项根目录的CLAUDE.md讲各端共用的规则。第三个是钩子脚本的标准输入是 JSON 数据流不是普通参数。很多人都栽在这里过动不动就写成cat $1结果发现 reads 不到内容。正确做法是input$(cat)或者把脚本写成从 stdin 读取解析 JSON。还要记得用jq做字段提取比用 grep 硬抠字符串要可靠得多。第四个是模板仓库里不放私密信息。这是最重要的安全底线。我见过有人把数据库连接串、API token 直接写进CLAUDE.mdAI 在执行对话时有概率把它带进日志或者外部调用中潜在风险非常大。所有的密钥类信息必须通过环境变量注入模板里只保留变量名占位符。7.3 从“复制粘贴”到“体系化沉淀”的转变我前面写的这些本质上是一次思维转变的总结。最开始我也只是一个简单的复制粘贴玩家每次建项目都去旧的仓库里翻CLAUDE.md和命令目录然后慢慢补丁式地加内容。这种方式虽然能跑但每一次手工复制都是错误发生的窗口。当我开始用模板仓库统一管理之后新的问题出现了模板更新了老项目怎么合入解决方案就是我在 6.3 里写的 submodule 和定期回流。这套流程跑顺之后我的新项目从“初始化 Claude Code 环境”到“AI 能稳定地按项目规范工作”花的时间从原来的一个上午缩短到十分钟以内。这个收益不只是效率上的更重要的是确定性。以前每次都靠对话提示词去约束 AI效果随我的心情和技术水平波动现在模板就是制度制度就是产出质量。AI 依然是那个 AI但使用 AI 的方式已经变成了一条可追踪、可回滚、可团队复用的流水线。最后分享一个小技巧定期去翻一翻你项目里的.claude目录看看哪些命令模板半年都没被用过果断删掉。模板不是收藏癖的玩具留着不用的模板只会增加 AI 误触发的概率。保持精简保持克制的模板库比堆了一堆看似全面实则无用的文件更能让你在真正的任务里跑得更快。