如果你用 Claude Code 写过代码大概率体会过这种别扭模型本身很强但每次开新会话都得把项目背景、目录结构、编码规范、禁止事项重新念叨一遍。说少了它自由发挥说多了对话还没开始上下文已经被背景说明吃掉大半。我花了一段时间专门整理 claude-code-templates把零散的 prompt 碎片升级成了一套能直接复用的模板体系今天这篇就是为了把这套做法讲透——它是什么、怎么设计、怎么写、坑在哪以及最关键的怎么让它真正跑在你的项目里。这套东西适合两类人一类是已经用上 Claude Code 但总觉得“不够听话”的开发者另一类是准备给团队统一 AI 编程规范的技术负责人。模板不是把 prompt 写得越长越好而是把高频、重复、容易出错的决策点提前固化让模型每次进入项目都能站在同一条起跑线上。下面我会从原理拆到实操尽量让你看完就能搭出自己的模板库。1. claude-code-templates 是什么模板机制与核心价值1.1 模板的真实载体不止是 CLAUDE.md很多人以为 Claude Code 的模板就是往项目根目录放一个 CLAUDE.md 文件这其实是理解上的第一道坎。CLAUDE.md 确实是最常用的入口但从完整角度看模板体系至少包含四层项目级 CLAUDE.md放项目根目录描述项目结构、技术栈、常用命令、注意事项每次会话启动时自动注入。全局 CLAUDE.md放在用户目录下作用于所有项目适合放编程通用偏好、跨项目的代码风格约定。Slash Commands放在.claude/commands/目录下的 Markdown 或脚本文件例如/review、/refactor、/commit把固定任务逻辑封装成一个命令。Hooks 配置在.claude/settings.json中定义的钩子在特定事件如 PreToolUse、PostToolUse触发时执行检查或提示能把模板的“强制力”从引导变成约束。这四层不是相互替代而是层层叠加。我实际用下来的感觉CLAUDE.md 负责“背景信息”Slash Commands 负责“任务套路”Hooks 负责“红线检查”。三者组合起来才构成一个完整的模板系统。如果只写一个又长又杂的 CLAUDE.md模型依然会在具体任务环节失去方向。1.2 模板解决的是“一致性”问题Claude Code 的能力不是问题问题是同一个任务在不同会话里输出质量像开盲盒。上午让它写一个 API 接口它会先问你要数据库表结构下午让它写同样的接口它直接开始用假设的字段名硬编码。这种不稳定不是模型变笨了而是上下文里没有稳定锚点。模板的作用就是给模型提供稳定锚点。拿一个电商项目举例我在 CLAUDE.md 里写死三件事项目使用 Node.js 18 TypeScript数据库采用 PostgreSQL所有时间字段统一使用 UTC。之后每次会话模型默认按这套约定执行不需要我反复确认。这种效果的实现成本很低就是几行固定的描述文本但它从根上消除了大量重复对话。更深一层模板还解决团队协作的一致性。多人维护同一个仓库时新人的 prompt 习惯和老手完全不同。通过统一模板至少能让模型面对所有人时都表现出同一种“项目常识”减少因个人表达差异导致的代码风格漂移。这一点在 Code Review 场景尤其明显下文会展开讲。2. 模板体系的设计思路与分类方法2.1 先按使用场景切分而不是按文件类型切分新手最容易犯的错是把所有想说的都塞进一个 CLAUDE.md结果文件越来越长最后模型反而抓不住重点。我的建议是反过来先列出你日常使用 Claude Code 的高频任务场景再为每个场景决定用什么载体承载。我常用四类场景分类背景型场景新会话启动、新功能开发、理解既有代码。这类场景需要的是项目背景和代码规范对应 CLAUDE.md。任务型场景写测试、生成提交信息、做代码评审、执行重构。这类场景有固定的输入输出格式对应 Slash Commands。约束型场景禁止修改某个目录、禁止删除迁移文件、必须在提交前跑 lint。这类场景需要强制检查对应 Hooks 配置。组合型场景比如“从新建分支到提交 MR”的一站式流程则需要把 CLAUDE.md、Commands、Hooks 组合使用。这个分类的妙处在于你能立刻看出哪些内容是“一次性背景”哪些是“可复用流程”。背景型内容写成叙述文字任务型内容写成带步骤的模板约束型内容写成可执行的检查条件。三者性质不同硬塞在一起只会两败俱伤。2.2 一条好模板的四个特征在看过社区里大量 templates 仓库后我总结出好模板的四个特征也当作自我检查标准第一具体指令大于抽象描述。与其写“请编写高质量的代码”不如写“所有函数必须包含 JSDoc 注释公共函数需要相邻的单元测试”。模型对具体约束的响应稳定性远高于对抽象形容词的理解。第二带示例优于只讲规则。给模型一个输入输出对比给它十行规则更管用。例如模板里写清楚“提交信息格式type(scope): subject例如feat(auth): add refresh token rotation”模型生成的提交信息就会稳定很多。第三边界意识明确。好的模板会告诉模型什么不要做。例如“不要修改src/generated目录下的文件”“不要在业务代码里直接调用数据库驱动必须走仓储层”。没有边界的模板约束力几乎为零。第四可组合可裁剪。模板不应该是一整块巨石而应该像积木。拆开成核心背景、任务流程、红线规则三部分项目变化时只需替换对应模块。我见过很多模板仓库把几十个项目共性全部写进一个文件换个新项目立刻水土不服就是因为没有组合思维。下面这个表格是我自己对比过的两种写法建议大家感受一下差异维度糟糕模板较好的模板任务指令“优化这段代码”“重构handlePayment函数拆分超过 50 行的 if 体补全错误处理保持对外返回结构不变”约束表达“注意安全”“禁止使用eval禁止在客户端日志打印 token 或密钥”示例提供“写一个接口”“参考src/api/users.ts的写法新接口必须包含参数校验、错误码映射和 OpenAPI 注解”目标衡量“提升可读性”“代码圈复杂度不超过 10单函数行数不超过 60注释覆盖所有公共方法”3. 从零搭建自己的模板库目录结构与核心配置3.1 初始化目录一个能放进任何项目的结构我自己维护了一套模板仓库目录结构长这样project-root/ ├── CLAUDE.md ├── .claude/ │ ├── commands/ │ │ ├── review.md │ │ ├── commit.md │ │ ├── refactor.md │ │ └── test.md │ ├── settings.json │ └── hooks/ │ ├── pre-commit-check.sh │ └── post-tool-use.sh └── docs/ └── templates/ └── api-endpoint.md这套结构的核心逻辑是CLAUDE.md 只放项目级背景commands 放任务模板settings.json 驱动自动化检查docs/templates 放更细的场景模板供命令引用。刚开始不需要一次建全但建议至少把 CLAUDE.md 和 commands 分开。CLAUDE.md 的写法很有讲究。我见过最有效的版本开头不是“这是一个 ... 项目”而是直接列出项目关键事实和硬性约束# 项目背景 - 项目类型Node.js 18 TypeScript Express 5 的 REST API 服务 - 数据库PostgreSQL 15通过 Prisma ORM 访问 - 部署环境Docker 容器目标平台为 Linux x64 - 包管理pnpm禁止使用 npm 或 yarn历史迁移成本高 # 代码规范 - 所有公共代码必须带 JSDoc 注释接口请求/响应用 zod 校验 - 时间字段统一使用 UTC 存储ISO 8601 字符串输出 - 异常处理统一使用 AppError禁止直接 throw new Error - 文件命名kebab-case组件命名PascalCase # 高频命令 - 启动测试pnpm test -- --watch - 代码检查pnpm lint --fix - 生成迁移pnpm prisma migrate dev # 禁止事项 - 不要修改 src/generated 目录下的任何文件 - 不要绕过 Prisma Client 直接写 SQL除非在 prisma/migrations 内 - 不要引入新的全局状态库当前用 Zustand 已经足够这段内容看起来简单但是信息密度很高。我特意把“禁止事项”单独放一块因为模型对否定式约束的遵循程度往往取决于它是否在上下文激活后被反复看到。CLAUDE.md 会在每次会话自动注入所以这些约束能持续起作用。3.2 编写 Slash Command 模板让重复任务一键触发Slash Commands 是 Claude Code 模板体系里最提效的部分也是我最推荐先动手的部分。它允许你把一个任务的处理流程固化成 Markdown 文件然后通过/命令名直接触发。一个典型的命令文件长这样--- description: 对指定代码执行分层 Code Review argument_hint: 目标文件或目录路径 allowed-tools: Read, Grep --- # Code Review 任务 你需要评审以下目标{{argument_hint}} 请严格按下列流程执行 1. 先阅读目标文件的完整内容再搜索相关依赖的实现。 2. 按四个维度输出评审结果正确性、性能、可维护性、安全性。 3. 每个维度先给结论再列出具体行号和修改建议。 4. 如果发现问题必须给出可复制的修复示例而不是只说“建议优化”。 5. 最后输出一条 review summary用英文总结控制在 60 词以内。 ## 边界 - 只做评审不要主动修改代码。 - 如果目标文件超过 300 行在结论前增加“文件概况”段落。 - 安全维度必须检查输入校验、鉴权、敏感信息泄露三类问题。这个模板里最关键的变量是{{argument_hint}}用户敲/review src/services/payment.ts时这个占位符会被替换成src/services/payment.ts。使用 frontmatter 字段description能让斜杠命令在候选列表里显示用途argument_hint则提示使用格式。我通常把这类命令文件控制在 30 行以内因为太长的话模型在执行中途容易丢失子步骤。关键不是列出所有细节而是给出稳定的执行框架并用“边界”小节防止模型跑偏。这里有个经验之谈命令模板里最好显式声明“只做什么不做什么”比如评审场景的“不要主动修复”这能避免模型自作主张改代码。3.3 Hooks 与模板联动把约束变成自动化检查光靠 CLAUDE.md 提醒模型还是可能在某次执行中“忘记”规则尤其是在处理长任务时。Hooks 机制则能把部分约束变成硬性检查在动作发生前后触发脚本不满足条件就阻止或提示。我常用的一个配置是把 Git 提交前的 lint 检查接到 Claude Code 的工作流里{ hooks: { PreToolUse: [ { matcher: Write, command: .claude/hooks/pre-write-check.sh } ], PostToolUse: [ { matcher: Edit, command: .claude/hooks/post-edit-check.sh } ] } }pre-write-check.sh 的写法很朴素检查写入路径是否落在禁止目录里#!/usr/bin/env bash file_path$1 if [[ $file_path src/generated/* ]]; then echo 禁止修改 src/generated 目录下的自动生成文件 exit 2 fi exit 0Hooks 与模板的联动本质上是把写进 CLAUDE.md 的“禁止事项”复制到脚本判断条件里。注意这里存在冗余但冗余是有意的因为文本提醒负责柔性引导脚本检查负责硬性拦截。两条腿走路模型越界概率才会降到最低。需要特别提醒的是Hooks 命令里配置的外部脚本需要可执行权限否则会静默失败。我踩过这个坑配置好后怎么都没反应最后才发现是chmod x忘了执行。之后我习惯在加入脚本后立即检查ls -l确保权限位正确。4. 开源模板库分析与实战选型4.1 从哪些渠道找可复用的模板社区里已经有很多 claude-code-templates 相关的仓库值得参考。GitHub 上搜索awesome-claude-code、claude-code-templates、claude-code-commands都能找到大量内容。我挑仓库的标准很直接看维护活跃度和示例数量而不是看 star 数。很多高 star 仓库只是聚合链接真正包含完整模板内容的往往来自实际项目沉淀。值得关注的模板类型包括代码评审提示词、提交信息生成、技术栈迁移、测试用例生成、文档注释补全等。比如一个用 TypeScript 开发后端 API 的项目最常用的模板就是“生成 controller”“生成 service 测试”“评审数据库迁移脚本”这三个。把这些模板下载下来后不要直接扔进项目先读一遍看看它的约束条件和示例是否符合当前仓库的工程习惯。4.2 我的模板适配流程与躲坑指南拿到一个开源模板我会按三步做适配。第一步删掉与当前项目无关的约束。很多模板里残留作者个人偏好比如“必须使用 PEP8”只适用于 Python 项目放进 Node 项目里就是噪音。第二步把示例代码替换成当前项目真实文件。模板里写的“参考src/utils/date.ts”要改成自己项目的真实路径不然模型找不到参考对象。第三步补充当前项目的负面清单。开源模板不会知道你的src/generated目录不能动这必须自己加进去。躲坑方面最大的坑是模板“覆盖一切”的冲动。有人觉得模板越多越好一口气装了 30 个 Slash Commands结果命令菜单里全是低频命令真正高频的/review反而被挤到下面。我现在的原则是高频任务用 Slash Command低频任务直接自然语言对话。模板是给重复劳动用的不是给好奇心用的。另一个坑是模板版本与工具版本不匹配。Claude Code 迭代很快某些旧模板里的工具名或参数可能已经失效。遇到命令执行报错先别怀疑模板逻辑优先检查官方 changelog 或工具使用说明把allowed-tools里的旧名称更新掉往往能解决一大半问题。5. 常见问题与排查技巧实录5.1 模板不生效先查路径、再看大小写“我明明放好了 CLAUDE.md为什么模型完全不按里面的要求做”这是我被问到最多的问题。排查路径其实很固定。第一步确认文件位置。CLAUDE.md 必须放在项目根目录且大小写完全一致。很多人在 Windows 上创建了claude.md或Claude.md大小写不对工具识别不到。Slash Commands 必须放在.claude/commands/下文件名是命令名比如review.md对应/review中文名也可以但建议保持英文避免输入切换麻烦。第二步确认是否被项目级配置覆盖。Claude Code 配置存在优先级用户目录的全局 CLAUDE.md 与项目级 CLAUDE.md 会合并但 settings.json 里的某些设置可能覆盖命令模板的默认值。遇到模板行为不符合预期检查.claude/settings.json中是否设置了与模板冲突的permissions或env。第三步确认上下文长度。CLAUDE.md 自动注入所占用的 token 会随文件长度线性增长。如果文件超过 8000 字符模型在高强度对话后期可能淡化早期指令表现就是“越聊越不听话”。我的经验是项目级 CLAUDE.md 控制在 5000 字符内剩余背景拆进对应命令模板按需加载。5.2 上下文占用过高给模板做瘦身Claude Code 的上下文窗口有限而 CLAUDE.md 是每次会话都要占用的固定开销。很多模板仓库追求大而全塞进去大量背景描述结果一次会话啥都没干先被吃掉几千 token。瘦身的方法有两条主线。一条是精简措辞把描述性废话改成清单。比如“本项目是一个基于微服务架构的电商平台后端包含用户、订单、商品、支付等核心模块使用 Kafka 进行异步消息传递Redis 用于缓存热点数据”这段完全可以精简成“电商后端user/order/product/payment 模块Kafka 异步Redis 缓存”。模型需要的不是散文是事实。另一条是把长背景挪进需要时才加载的命令文件里。项目整体架构图或部署说明并不是每个任务都需要。把这些内容放到/architecture命令中使用时再通过占位符引入而不是写进 CLAUDE.md。这样日常会话的固定开销能下降 30% 到 50%实测效果非常明显。5.3 模板之间的优先级冲突当你同时有全局 CLAUDE.md、项目 CLAUDE.md 和 Slash Commands 时可能会遇到规则冲突。比如全局模板要求“所有提交信息遵循 Conventional Commits”项目模板却想简化成“直接写改了什么”。模型面对冲突时行为并不稳定它可能随机选择某一条执行。我的解决方法是明确层级全局 CLAUDE.md 只放所有人都认同的通用规范比如“禁止提交包含密钥的文件”“必须补齐测试”项目级 CLAUDE.md 放当前仓库特有的规范两者冲突时以项目级为准。Slash Commands 内部如果有独立规则则在命令文件开头显式声明“忽略项目模板中与本命令冲突的部分”。这个规则要在 CLAUDE.md 里用一句话写清楚“如果后续指令与本文冲突以当前任务命令的显式要求为准。”模型对优先级声明敏感一旦声明了规则它会主动避免二次询问这也算是我摸索出的小技巧。最后再分享一点我的个人体会整套模板体系从搭到改我大概迭代了三个版本。第一版把什么都写进 CLAUDE.md文件天天膨胀后来强迫自己按场景拆命令才真正进入良性状态。现在我的习惯是每当同一个任务第三次用自然语言重复就把它固化成模板每两周翻一次模板库删掉使用频率最低的那一两个命令。模板不是收藏品是消耗品常用常新才有价值。如果这篇文章能让你少走一点弯路那就值得了。