最近我把攒了很久的 claude-code-templates 仓库重新整理了一遍从一堆零散的提示词碎片收敛成了一套可以直接复制到任意项目里的模板集。Claude Code 这个终端 AI 编程助手本身很强但裸用的时候你会明显感觉到一个问题每次开新会话它都要重新认识你的项目重新理解你的代码风格重新想你可能会用哪些命令。模板集解决的就是这件事——把项目背景、工作流、工具调用规则全部固化下来让 AI 从“能聊天”变成“按团队规矩干活”。这套东西适合谁如果你已经在用 Claude Code 写代码、做代码审查、维护老项目或者正打算给团队统一一套 AI 编程规范那这套模板的思路和具体文件可以直接抄。没有接触过 Claude Code 的朋友也不用怕下面我会从最基础的文件结构讲起每个模板为什么这么写、踩过哪些坑都会说清楚。1. 为什么我会专门维护一个 claude-code-templates 仓库1.1 裸用 Claude Code 的三个痛点我刚开始用 Claude Code 的时候体验很分裂。单次对话里它的代码理解能力确实惊艳但换个会话、换个项目一切又要从头来。第一是上下文缺失每开一个新会话都要花十到十五分钟把项目背景、技术栈、目录结构、启动命令重新喂一遍讲漏一个细节后面给出的建议就偏了。第二是风格漂移同一个项目今天让它改一个函数明天让它加一个接口两次生成代码的风格可能完全不一样有时候用单引号有时候用双引号有时候返回 Promise有时候直接 return。第三是重复劳动代码审查、生成提交信息、跑冒烟测试这些高频操作每次都要打一大段提示词稍微写得不严谨它就会漏掉某条检查项。这三个痛点叠加在一起就是典型的“单次聪明、整体失忆”。企业里 LLM 编程要落地核心不是模型能力而是工程化地把团队知识沉淀下来。我当时的判断是与其每次手写提示词不如把团队规范、项目背景、常用流程全部做成模板文件让 Claude Code 启动时自动加载。1.2 模板仓库的定位把“一次性对话”沉淀成“可复用资产”claude-code-templates 这个名字听起来像一堆提示词文件实际上它的定位更像“AI 编程的项目底座”。我把它拆成了四层CLAUDE.md 负责长期记忆相当于给 AI 看的入职手册commands 目录负责高频操作相当于给 AI 配了一套快捷键hooks 负责自动化收口相当于在关键动作前加了一道检查岗skills 负责复杂技能相当于把多步骤流程打包成一个可复用的能力包。打个比方裸用 Claude Code 像是请了一个聪明但没经验的新人每次布置任务都要把前因后果讲清楚配置了模板仓库之后这个新人上岗第一天就拿到了公司规章制度、项目架构图、常用命令清单还知道哪些事必须做代码审查、哪些目录不能随便改。它不需要每次重新“试探”你的习惯因为模板已经把习惯写进去了。这套设计也决定了模板仓库不是一次性的。我维护它的方式是每次在真实项目里发现 AI 犯了低级错误或者发现某个高频操作值得固化就顺手把它写回模板。仓库里积累了三五十个模板之后新项目初始化基本就是复制过去改一改的事。2. 模板体系设计四层结构一次讲清2.1 第一层CLAUDE.md 项目记忆模板CLAUDE.md 是 Claude Code 启动时自动加载的项目记忆文件可以放在项目根目录也可以放在 ~/.claude 目录下作为全局配置。它是整套模板里优先级最高、也最容易写砸的一层。写得太短AI 记不住关键约束写得太长上下文被占满后续对话质量反而下降。我维护的 CLAUDE.md 模板固定分成六个区块每个区块都有明确用途项目一句话定位让 AI 在第一时间理解这个项目是干什么的、用户是谁、核心业务边界在哪。架构地图列出顶层目录、模块职责、数据流向AI 遇到问题先看地图再动手。常用命令安装依赖、跑测试、启动开发服务器、构建产物分别是什么避免它从 package.json 里瞎猜。编码规范缩进、引号、命名风格、组件组织方式、异常处理要求。这部分是风格漂移的根治手段。禁止事项不能动哪些目录、不能改哪些接口、不能用哪种方式实现。AI 的创造力有时是灾难必须提前划红线。当前状态正在进行的任务、最近的决策记录、已知技术债。这个区块我会用单独的 TODO 文件维护避免 CLAUDE.md 频繁改动。一个精简示例大概是这样的# 项目订单中台 ## 定位 负责订单创建、支付回调、退款流程的 BFF 层服务对接上游交易核心与下游仓储系统。 ## 架构 - src/modules/order 订单主流程 - src/modules/payment 支付回调 - src/shared 公共类型与工具函数 - 数据流向: controller - service - repository - MySQL ## 常用命令 - 安装依赖: pnpm install - 运行测试: pnpm test - 开发调试: pnpm dev ## 编码规范 - TypeScript 严格模式 - 函数一律使用 async 风格禁止 callback - 错误处理用自定义 OrderError 包裹禁止裸 throw string - commit 信息遵循 conventional commits ## 禁止事项 - 禁止修改 src/shared/logger.ts 的日志输出格式 - 禁止在 repository 层直接写业务逻辑 - 禁止绕过支付回调的状态机直接更新订单状态这份文件写完之后AI 在后续对话里会自动引用其中的规则。比如你让它改订单状态它看到“禁止绕过支付回调的状态机”就会主动追问或拒绝不安全的改法而不是闷头就写。2.2 第二层自定义斜杠命令模板如果说 CLAUDE.md 是静态知识commands 目录就是动态技能。Claude Code 支持把 Markdown 文件放到 .claude/commands 目录下每个文件对应一个斜杠指令。文件开头的 YAML frontmatter 用来声明命令的用途、参数提示、可用工具和模型正文就是给模型的指令。这层设计要回答一个关键问题哪些操作值得固化成命令我的标准是“每周至少用三次以上”。代码审查、提交信息生成、单测补齐、冒烟测试、接口文档更新这些都属于高频操作。低频的、一次性的操作不值得占命令位。命令模板的正文和普通提示词最大的区别在于它要写“流程”而不是写“要求”。比如代码审查命令不能只说“请审查我的代码”而是要写明怎么拿 diff、按什么顺序读改动、每条问题以什么格式输出、发现阻塞问题时要执行哪个检查命令。AI 不是不愿意干活而是不知道怎么干才算符合你的标准。2.3 第三层hooks 自动化模板hooks 是 Claude Code 的事件钩子机制可以在 AI 调用工具之前、之后或者对话结束、请求暂停时执行一段自定义脚本。这一层我把它当作安全护栏和质量闸门。最常用的是 PreToolUse也就是在 AI 准备调用某个工具之前先执行检查脚本。比如 AI 准备执行 git push我们可以让 hook 先检查当前分支是否跑过测试、是否生成过变更记录不满足条件就中断操作并给出提示。再比如 PreToolUse 拦截 Bash 命令可以做一个敏感命令黑名单防止 AI 误操作生产环境的删除命令。hooks 的真正价值是让模板从“建议”变成“约束”。CLAUDE.md 写得再好AI 也可能偶尔忽略但 hooks 是硬性的脚本返回非零退出码工具调用就会被阻止没得商量。团队里有这条硬约束AI 出格的概率会小很多。2.4 第四层Agent Skills 技能模板Agent Skills 是比 commands 更复杂的可复用技能单元放在 .claude/skills/技能名/SKILL.md 下。每个技能通过 frontmatter 里的 name 和 description 声明正文写完整的工作流程、输入输出约定、质量要求。我在实战中的分界是这样commands 适合“一个回合就能说清楚的操作”比如生成提交信息skills 适合“需要多个步骤、可能还要调用多轮工具才能完成的任务”比如“修复 eslint 报告并补齐变更测试”就涉及分析错误列表、定位源码、修改代码、跑测试四个阶段。技能包里甚至可以把参考实现、常见陷阱、验收清单都写进去AI 调用技能时相当于执行了一套 SOP。这四层结构的核心不是堆文件而是分层治理。记忆归记忆、操作归操作、约束归约束、技能归技能。每层都有独立演进的空间不会因为某项规则变化导致整个配置推倒重来。3. 实操从零搭建你的 claude-code-templates3.1 初始化目录结构与规范约定模板仓库的物理结构我建议长这样claude-code-templates/ ├── CLAUDE.md ├── .claude/ │ ├── commands/ │ │ ├── code-review.md │ │ ├── commit-msg.md │ │ └── smoke-test.md │ ├── hooks/ │ │ ├── check-before-push.sh │ │ └── block-dangerous-command.js │ ├── settings.json │ └── skills/ │ ├── fix-lint-and-test/ │ │ └── SKILL.md │ └── api-doc-updater/ │ └── SKILL.md ├── templates/ │ ├── frontend/ │ │ └── CLAUDE.md │ └── backend/ │ └── CLAUDE.md └── README.md如果你只是单个项目使用直接把 CLAUDE.md 和 .claude 目录拷到项目根目录即可。如果要在团队内推广我会把整个仓库作为独立 git 仓库管理各项目用脚本或 git submodule 拉取再在项目里覆盖差量配置。注意用户级的全局模板放在 ~/.claude 下项目级的放项目根目录两者冲突时我这边约定项目级优先保证不同项目的特殊规则不被全局配置污染。目录建好之后第一件事不是写模板而是设置 settings.json。这个文件控制权限、hooks 和模型参数。基本配置长这样{ permissions: { defaultMode: acceptEdits, allow: [ Bash(pnpm test), Bash(git diff), Read ], deny: [ Bash(rm -rf *), Bash(git push --force) ] }, hooks: { PreToolUse: [] }, model: claude-sonnet-4-20250514 }这里要提醒一下permissions 里的 allow/deny 规则一定要谨慎。写得太宽松AI 乱执行命令的风险会增加写得太严格每一步都弹授权也影响效率。我的经验是允许白名单化的常用命令拒绝明显危险的全局操作。3.2 三个拿来即用的命令模板第一个是代码审查命令。它是我整个仓库里用频次最高的模板核心是把审查流程拆成四个阶段获取改动、读上下文、逐文件检查、输出结构化报告。--- description: 审查当前分支改动的代码质量 argument-hint: [文件名或模块名可选] --- 执行以下流程 1. 运行 git diff main...HEAD --stat 获取改动文件列表。 2. 如果用户指定了文件或模块优先审查指定范围否则按列表逐个文件审查。 3. 对每个文件先读取完整内容再运行 Grep 搜索关联调用理解改动影响面。 4. 重点检查边界条件、错误处理、类型安全、性能隐患、是否符合 CLAUDE.md 里的编码规范。 5. 输出格式 [严重] 阻塞合并的问题给出具体行号和修改建议 [建议] 可优化项不阻塞合并 [问题] 需要确认的疑问点 6. 如果存在严重问题运行 pnpm test 验证当前是否失败并报告失败用例。第二个是提交信息生成命令。它解决的是“每次生成 commit message 都要反复灌输规范”的痛点。--- description: 根据当前 diff 生成符合规范的 commit message argument-hint: [提交范围说明可选] --- 1. 运行 git diff --cached查看已暂存改动。 2. 根据 conventional commits 规范判断提交类型feat / fix / refactor / docs / test / chore。 3. 主体部分用一句话概括目的说明部分列出关键的改动点和影响范围。 4. 如果用户传入 $ARGUMENTS优先按用户描述的侧重点生成。 5. 输出只包含提交信息不要输出额外解释不要使用 emoji。第三个是冒烟测试命令。它用来在改完核心链路之后快速确认主流程没坏。--- description: 对核心链路执行冒烟测试 argument-hint: [测试重点可选] --- 1. 读取 package.json 中 scripts 字段找到测试相关命令。 2. 先运行 lint 检查再运行测试命令 pnpm test。 3. 如果用户提供 $ARGUMENTS在测试命令后追加对应结果路径。 4. 收集测试输出找出失败用例分析失败原因。 5. 输出结果汇总如果失败给出根因分析不要只粘贴日志。这三个文件看起来只是几屏 Markdown但实战里它们能省下大量重复解释的时间。团队新人拿到这套命令不需要理解 Claude Code 的细节直接输入 /review、/commit-msg、/smoke-test 就能得到统一格式的输出。3.3 hooks 模板与自动化收口hooks 用起来比 commands 要麻烦一点但因为它是硬约束收益也更明显。我最常用的两个 hook 模板一个是 git push 前置检查一个是危险命令拦截。git push 前置检查的思路是在 AI 准备执行 git push 时先检查当前 Git 工作区是否有未提交的变更记录以及是否已完成代码审查。检查脚本用 Node 或 Shell 都行退出码 0 放行非 0 拦截。#!/usr/bin/env bash # .claude/hooks/check-before-push.sh set -euo pipefail CHANGELOG_STALE$(git diff --name-only HEAD | grep -c CHANGELOG || true) if [ $CHANGELOG_STALE -eq 0 ]; then echo 变更记录未更新请运行 /commit-msg 补充后重试 2 exit 1 fi exit 0然后在 settings.json 里挂上这个钩子{ hooks: { PreToolUse: [ { matcher: Git(git push), hooks: [ { type: command, command: bash .claude/hooks/check-before-push.sh } ] }, { matcher: Bash(rm -rf), hooks: [ { type: command, command: bash .claude/hooks/block-dangerous.sh } ] } ] } }这里有个重要细节 matcher 的写法要能匹配到对应工具调用。Git(git push) 匹配的是 Claude Code 内置的 Git 工具Bash(rm -rf) 匹配的是以 rm -rf 开头的 Bash 命令。匹配规则写宽了容易误伤写窄了又拦不住建议在真实项目里多测几轮再定稿。Stop 钩子我也很常用作用是在每次对话结束时自动记录消耗的 token 数和遗留问题把它追加到 .claude/session-log.md 里。这个日志在复盘“AI 为什么答非所问”时价值极高。4. 团队落地与提效实录4.1 把模板当作代码来审查模板仓库在团队里落地最容易犯的错是一拍脑袋写一堆命令然后期望所有人直接使用。结果往往是三分之一的人觉得不如手写提示词三分之一的人觉得模板太笨剩下的三分之一根本没装。我把模板当代码审之后情况好了很多。每个新命令在合入模板仓库之前必须过一轮“模板评审”能不能在三个以内步骤完成输出格式是否唯一会不会和已有命令冲突描述字段是否足够让模型在合适的时机主动调用评审不通过就打回重写标准和审业务代码一样严格。另外模板变更要有 chill 期。新命令先在个人项目里跑两周确认效果稳定再合入团队仓库。之前我把一个没验证过的重构命令直接推给团队结果它建议 AI 把整个 service 层拆了重写差点引发事故。4.2 上下文预算管理与模板瘦身模板用久了会膨胀。CLAUDE.md 动不动就上千行commands 越来越多AI 每次会话都被这些内容占掉大量上下文开始变得迟钝、忽略关键指令。我遇到过最夸张的情况是项目里 CLAUDE.md 写了完整的数据字典导致上下文窗口被灌满AI 连最基本的错误修复都做不好。解决办法是给模板设预算。CLAUDE.md 正文控制在 300 行以内超过的部分拆到 docs/ 目录用“按需读取”的思路。比如把数据字典移到 docs/database.md在 CLAUDE.md 里只写一句“涉及数据库字段时先读 docs/database.md”。这样 AI 在普通对话里不会加载数据字典只有真需要查字段时才会去读文件。commands 的正文也要克制。每条命令的指令不超过一屏超过就说明这个操作不适合做成命令应该拆成多个命令或升级成 skill。hooks 脚本同样要短复杂逻辑放到独立脚本文件里settings.json 里只放挂载点。4.3 版本管理与多项目同步机制多项目共用模板仓库最大的痛点是版本同步。A 项目和 B 项目对 CLAUDE.md 的需求可能完全相反盲目更新会把某个项目的规范覆盖掉。我现在用的是“模板仓库 项目差量”双轨制。模板仓库维护通用规则比如代码风格、工具使用约束、高危操作黑名单每个项目维护自己的差量文件比如特有目录、部署流水线、领域模型说明。同步脚本只复制 templates 目录里的通用模板不会碰项目级 .claude 下的差量配置。这样既享受了集中维护的好处又保留了项目灵活性。每次模板仓库发布新版本我会写一条简短的变更记录说明改了什么、为什么改、影响面在哪。其他项目拉取更新后至少要跑一遍已有的测试用例确认 AI 行为和之前一致再合入主干。5. 常见问题与排查技巧实录5.1 命令不生效或加载不到这是新手遇到最多的问题。装了命令文件但斜杠命令一直没出现大概率是文件放错了位置或者 frontmatter 格式有误。Claude Code 只读 .claude/commands 目录下的 Markdown 文件放在其他目录就不会被识别。frontmatter 必须严格按照 YAML 语法少一个冒号、多一个换行命令解析就会失败。还有权限问题。在 macOS 或 Linux 下hooks 脚本需要有执行权限否则会静默失败。我踩过的坑是明明 hooks 配置好了但执行 git push 时没有拦截排查半天发现脚本没有 chmod x。命令文件则要确认编码是 UTF-8带 BOM 的文件在部分环境下会解析异常。5.2 模型不遵守模板指令怎么办模板生效了但 AI 依然不按模板格式输出这是另一个高频问题。很多情况下不是模型故意的而是模板和目标任务在上下文里没有强绑定。CLAUDE.md 里的规则模型可能因为上下文过长而“遗忘”commands 里的指令可能因为用户提问太模糊而没有被严格执行。解决思路是给模板加“触发条件”。在 commands 的 description 里写清楚适用场景描述要提关键词因为模型依赖 description 判断何时应加载这条命令。在 CLAUDE.md 里把关键规则写进“禁止事项”区块而不是“建议”区块机器能真正区分“必须遵守”和“仅供参考”。如果还是不听可以在命令正文里加一句“如果不按照本指令执行直接回复无法完成任务”用后果压力提高约束力。5.3 多级模板冲突与覆盖优先级问题全局模板和项目模板并存时冲突是不可避免的。我的团队约定是项目级优先但这个优先级不会自动发生需要检查 Claude Code 的加载逻辑。如果你的场景里多个配置互相覆盖可以在会话中让 AI 输出它当前加载的 CLAUDE.md 摘要确认哪些规则生效、哪些被覆盖。更稳妥的做法是避免在全局和项目里定义同名的命令。全局放通用能力项目放专属能力名字尽量不重复。真有同名需求时比如都叫 /review那就得明确它们想解决的问题是否一致不一致就改名让语义更精确。整理 claude-code-templates 这件事我最大的体会是模板的价值不在第一次安装而在每一次项目复盘后的迭代。每次 AI 在一个新环境里犯了低级错误我都会顺手把教训写回 CLAUDE.md每次有人操作某条命令后还要手动修正格式我就知道这条命令该改写了。等仓库里的模板积累到一定规模你会发现新项目接入 Claude Code 的成本变得极低因为它已经不再是“从零训练一个 AI 助手”而是“带着一整套成熟手册上岗”。最后再分享一个小习惯任何模板的升级都不要直接覆盖生产仓库先在临时分支跑一遍旧用例确认行为不劣化再合入。这个流程很笨但能帮你避开“模板更新之后 AI 突然不会干活”的尴尬。