最近我在几个项目里统一搭了 claude-code-templates 这套东西折腾完最大的感受是很多人用不好 Claude Code真不是模型能力的问题而是从头到尾没给助手立过规矩。所谓 claude-code-templates简单说就是一组写给 Claude Code 看的“项目说明书 行为指南 常用操作快捷键”它把项目的技术栈、代码规范、禁忌事项、高频任务流程全部固化成一堆 Markdown 文件让 Claude Code 每次启动时先“读一遍再干活”。这样它在每个项目里都有统一的上下文和操作口径不会同一个需求这次这么写、下次那么写。这篇内容我把我搭模板的完整思路、目录结构、可以直接抄走的配置以及踩过的坑全部整理出来适合正在重度使用 Claude Code、或者打算把这类终端编程助手引入团队的朋友。1. 先把概念理清楚claude-code-templates 到底在管什么1.1 模板的本质给模型一本“项目手册”很多人第一次打开 Claude Code第一句话就是“帮我写一个登录功能”。模型确实会写但它不知道你的项目是什么技术栈、数据库在哪、有没有现成的认证封装、代码风格是什么。于是它一边猜一边问一次对话能浪费一多半时间在澄清问题上。模板就是为了解决这个问题。它的本质是把那些每次都要重复交代的背景信息——项目是什么、技术栈是什么、有哪些约定——和操作边界——哪些能改哪些不能改、用什么命令跑测试——提前写进文件让 Claude Code 在开工前自动读取。这就像给新员工发了一本《项目手册》他不用事事都来问你。你可以把 claude-code-templates 理解成“提示词的资产化工程”不再是临时在对话框里打一段话而是把高频、稳定、可复用的提示词沉淀成文件放进固定目录由工具自动加载。这也是它和普通提示词最大的区别——普通提示词是一次性消费品模板是可积累的工程资产。你今天写的一段 review 要求如果只是粘贴在对话里明天就消失了如果写进模板文件它就会一直起作用还能被团队其他人复用。1.2 没有模板和有模板差异到底有多大我用一个真实的对比来说明。假设一个 Next.js Prisma 的项目团队约定所有 API 路由必须先做鉴权再处理业务。没有模板的时候你让 Claude 新增一个用户资料接口它很可能直接生成一个裸接口连鉴权都没加你还得事后在 review 阶段自己发现。有模板的时候CLAUDE.md 里明确写了“API 路由必须包含 auth 校验否则不得提交”Claude Code 生成完代码会自己先检查一遍缺了校验它会主动补上。这不是模型变聪明了而是模板把团队规范平移给了它。另一层差异体现在高频操作的效率上。团队里最常做的几件事——跑测试、生成提交信息、做 code review——如果你把它们做成了斜杠命令在对话框里输入一行/reviewClaude 就会按你预设的检查清单逐项过一遍代码。没有模板的时候你得每次手打一整段“请以资深工程师视角从边界条件、类型安全、性能、规范四个维度 review 以下代码……”这种又臭又长的话。一次两次无所谓天天这么干时间就是这么省下来的。1.3 模板体系的三个层级我实际使用中会把模板分成三层全局层、项目层、会话层。全局层~/.claude/CLAUDE.md和~/.claude/commands/等目录管的是个人通用的工作习惯和常用命令所有项目共用。项目层项目根目录下的CLAUDE.md和.claude/commands/管的是这个项目特有的技术栈、团队规范和专用命令。会话层你在对话框里临时输入的指令以及用/memory之类的命令保存的临时要点属于即时补充。这三层是叠加生效的全局层管共性项目层管个性会话层管临时。设计模板时先想清楚某条规则到底属于哪一层能避免很多“规则打架”的坑。我后面单独有一章讲冲突排查这里先记住这个分层模型后面所有的实操都建立在它上面。2. 搭建模板前的三个核心设计决策2.1 决策一这条规则放全局还是放项目第一原则是——凡是和具体项目无关的都放全局凡是和项目强相关的都放项目。比如“修改依赖锁文件必须走 pnpm”这条对你的所有 Node 项目都成立放全局。比如“数据库迁移文件必须经过 DBA review”这条只有你们团队有这个流程放项目。我见过有人把公司特有的部署规范写进个人全局模板换到另一个项目之后Claude 动不动就按那套规则办事看起来非常奇怪。后来我统一收口全局模板只放三条——输出用中文、先看需求再动手、禁止删除没有版本控制的文件。其余内容全部下沉到项目模板。全局模板写得越薄通用性越强翻车概率越低。2.2 决策二写行为规范还是写任务指令行为规范是“怎么干活”的约束比如代码风格、禁止事项、工作流程放进 CLAUDE.md。任务指令是“做什么事”的流程比如 code review、生成提交信息、初始化模块做成斜杠命令。很多人把两者混在一起——CLAUDE.md 里写了一大堆操作流程命令文件里又写一堆行为约束结果 Claude 读起来很乱执行的时候经常张冠李戴。我的做法很明确行为规范解决“它平时怎么表现”任务指令解决“我叫它做事时它先做什么再做什么”。两者拆开之后模板的可维护性会明显好很多。CLAUDE.md 里的每一条规范都应该是长期有效的约束命令文件里的每一条流程都应该是完成任务的具体步骤。如果一个命令文件里出现了“你应该遵守项目规范”这种话基本就是放错地方了。2.3 决策三模板的颗粒度怎么控制模板不是越全越好。我见过有人把 CLAUDE.md 写到 300 多行结果模型每次启动都要读一大堆内容上下文预算被严重挤占响应速度也明显变慢。我的经验是CLAUDE.md 控制在 60 行以内只写“不说会犯错”的信息命令文件控制在 20 行以内只列检查清单和输出格式更复杂的流程拆成多个命令串联分步执行。颗粒度拿不准的时候问自己一个问题这句话如果漏掉了Claude 会做错事吗如果会写进去如果只是锦上添花先不放。我一开始也很贪心把“建议使用 ErrorBoundary”“建议使用 useMemo”这种软建议全写进去结果 Claude 在无关紧要的地方反复纠结。后来删掉这些软建议只保留硬约束输出质量反而上去了。3. 实操从零搭一套可复用的 claude-code-templates3.1 第一步写好 CLAUDE.md 这份“项目说明书”直接给一份我在项目中实际使用的模板结构你可以按项目情况改完直接用# 项目说明 这是一个基于 Next.js 14 TypeScript 的 SaaS 计费项目核心目录为 src/app、src/lib、src/db。 ## 技术栈与关键依赖 - Next.js App Router、TypeScript、Prisma、PostgreSQL - 包管理器pnpm测试Vitest Playwright - 鉴权统一走 src/lib/auth.ts 中的 requireAuth() ## 常用命令 - 安装依赖pnpm install - 开发服务器pnpm dev端口 3000 - 测试pnpm test端到端测试pnpm test:e2e - 构建pnpm build不要使用 npm run build ## 代码规范 - 组件使用函数式写法禁止 class 组件 - 所有 API 路由必须先调用 requireAuth() 鉴权 - 数据库变更必须同时提交 Prisma migration - 错误处理统一返回 { code, message } 结构 - import 顺序react → 第三方库 → 本地模块 ## 禁止事项 - 不要修改 src/lib/config.ts 中已存在的默认值 - 不要绕过 eslint/vitest 直接提交代码 - 不要删除尚未纳入版本控制的文件写好之后你要理解它为什么有效每条规范都是“如果漏了会犯错”的硬约束而不是“最好这样做”的软建议。Claude Code 读取它之后生成代码时会在内部对照这个清单。我加上这一段之后生成的接口代码基本都自带鉴权review 阶段的返工量明显少了。项目里的CLAUDE.md也应该纳入版本控制这样团队所有人都能共用同一套规则。3.2 第二步把高频操作变成斜杠命令斜杠命令是 claude-code-templates 里我利用率最高的一块。它解决的问题是把所有“需要长篇大论交代背景”的任务变成一行命令。做法是在项目的.claude/commands/目录下新建一个 Markdown 文件文件名去掉扩展名就是命令名。比如review.md对应/review。文件内容可以带一个 YAML 头部可选和正文提示词。这是我常用的写法--- description: 对指定代码做一次全面审查 argument-hint: 文件路径或代码片段 --- 请以资深工程师视角对以下代码做一次全面 review $ARGUMENTS 检查维度 1. 边界条件与错误处理是否完整 2. 类型安全是否存在 any、非空断言、隐式 any 3. 性能隐患重复渲染、资源未释放、O(n²) 循环 4. 是否违反项目 CLAUDE.md 中的规范 输出格式按【严重 / 一般 / 建议】三级列出问题每条给出具体位置和修改建议。这里的$ARGUMENTS是占位符用户输入/review src/lib/api.ts时后面的src/lib/api.ts会被填充到$ARGUMENTS位置。argument-hint则起到提示作用Claude 会知道这个命令期望接收什么参数即使你记不住用法它也会提醒你。除了 review我还会做这些常用命令/commit生成符合 conventional commits 规范的提交信息、/test跑测试并修复失败用例、/feature按既定模板新建功能模块、/explain解释一段陌生代码。每个命令都控制在 10 到 20 行正文只列检查点和输出格式不写长篇背景。技术栈背景已经在 CLAUDE.md 里了命令文件不需要重复。3.3 第三步给命令加上参数和条件分支斜杠命令最容易被忽略的是参数化能力。除了$ARGUMENTS整体占位符你还可以用$1、$2这种位置参数。比如一个新建组件的命令--- description: 按项目规范新建一个 React 组件 argument-hint: 组件名 [目录] --- 请按以下流程新建组件 1. 在 src/components${2:-} 下创建 ${1:组件名}.tsx 2. tsx 文件遵循函数式写法包含 Props 类型定义 3. 组件导出使用命名导出 4. 如果 ${1:组件名} 包含 Table/Form 后缀自动加上对应的通用逻辑这种写法适合需要“按输入动态调整”的场景。不过我的建议是命令文件不要太贪心。超过 30 行、带有大量条件逻辑的命令往往还不如拆成两三条命令再配合对话逐步执行更稳。原因很简单条件分支越多模型理解出现偏差的概率就越大一旦条件判断错了整个流程都会跑偏。3.4 第四步用技能目录沉淀“专业知识”如果你的项目里有一些非常专业、需要反复参考的知识——比如内部的权限模型、数据字典、支付流程时序——这些内容不适合全塞进 CLAUDE.md不然上下文压力太大。我会把它们整理成“技能包”的形式放在.claude/skills/目录下每个技能一个子目录里面用SKILL.md描述“什么时候该用、怎么用”再放若干参考文档。Claude Code 会在相关任务出现时自动调用这些技能比把所有知识塞进启动目录优雅得多。到这里一个清晰的分工就出现了CLAUDE.md 放“行为约束”commands 放“任务流程”skills 放“专业知识”。三者合起来就是一套完整的 claude-code-templates 体系。这个分工也是我踩了两次坑之后才想明白的——第一次是把专业知识全塞进 CLAUDE.md上下文直接爆掉第二次是把任务流程也塞进 CLAUDE.md模型每天忙着背流程活都不干了。4. 常见问题与排查技巧实录4.1 模板写了但不生效问题出在哪最常见的原因有三个路径不对、文件名不对、目录没刷新。CLAUDE.md 必须放在项目根目录斜杠命令必须放在.claude/commands/目录下文件名用英文短横线小写不带空格。如果文件放错地方或者名字被系统自动改成了CLAUDE.md.txt怎么调整都不会生效——这种事在 Windows 上尤其常见。另外Claude Code 对模板的加载是有缓存的。有时候你改了 CLAUDE.md新会话读取到的还是旧内容。我实测下来最简单有效的办法就是开一个新会话或者关闭终端重开。如果还是不生效就检查一下文件是不是被.gitignore忽略、是不是放在了 git 仓库之外。这些低级问题占了排查量的一大半先排除它们再往深里查。4.2 模板太长把上下文和响应速度拖垮了这是模板体系最容易被低估的风险。CLAUDE.md 和命令文件都会占用模型的上下文空间如果模板总计超过几千个 token模型留给实际代码分析的余量就会变小输出质量和速度都会下降。我自己的体验是一台本来响应很快的项目把模板加长之后明显感觉 Claude 的思考变慢了生成的代码也更容易跑偏。排查思路是先看哪些内容属于“冷知识”——比如支付流程时序、数据字典这种只在特定任务里用得到把它从 CLAUDE.md 挪到 skills 目录再看哪些规范是重复的——比如已经在代码里通过 ESLint 强制的内容就不用在模板里再写一遍最后看禁止事项是不是写多了保留三条最痛的就够。模板瘦身这件事收益立竿见影。4.3 全局模板和项目模板打架怎么办按我目前观察到的行为全局层和项目层模板是同时生效的叠加关系。项目层的规则并不会覆盖全局层而是两者都在。这就带来一个问题如果全局模板里写着“所有输出用英文”项目模板里写着“交互语言用中文”模型就会很纠结一会英文一会中文。我的解决办法是全局模板里不写和具体技术主题相关的内容只写个人工作习惯项目模板开头加一句“本文档中的规则优先级高于用户个人全局模板中与之冲突的部分”。另外在全局模板中明确留下“冲突处理原则”告诉模型遇到冲突时优先遵循更具体、更靠近当前任务的规范。这样大部分冲突都能自动化解。如果某条规则实在冲突得厉害我会把它从全局模板里删掉只保留在项目模板里。4.4 团队协作中的格式坑模板文件一旦提交到 Git 仓库就会遇到多人协作的问题。我踩过的坑包括行尾符从 LF 变成 CRLF 导致 Markdown 解析异常Windows 和 macOS 混用的团队里很常见命令文件被格式化工具乱改还有成员在 CLAUDE.md 里写入了个人偏好导致其他人用起来很别扭。建议团队在仓库顶部放一个.editorconfig把模板文件统一为 LF 行尾模板文件用.gitattributes标记为text eollfCLAUDE.md 的改动走 PR 评审命令文件也一样。把模板当代码对待它才不会慢慢腐烂。我见过一个团队半年没人动模板最后 CLAUDE.md 里的技术栈还是两年前的老版本那模板非但不能提效反而成了误导。5. 模板资产化它其实是团队的“第二套代码”5.1 用目录规范管理模板资产我自己的目录组织是这样的~/.claude/ CLAUDE.md # 个人全局行为规范 commands/ # 个人全局命令 review.md commit.md skills/ common/ 项目仓库/ CLAUDE.md .claude/ commands/ # 项目定制命令 review.md feature.md test.md skills/ payment-flow/ SKILL.md sequence.md命名统一用英文短横线小写不带空格和中文。这样无论个人还是团队都能一眼看出模板资产的边界在哪里。目录结构就是模板体系的骨架骨架清楚了往里面填内容就不会乱。5.2 模板的版本管理与迭代节奏模板不是一次写完就一成不变的它应该随项目演进。比如你们把组件库从 antd 换成了 shadcn/uiCLAUDE.md 里的技术栈说明就得同步更新。我习惯每隔一两周抽时间做一次“模板体检”翻一翻这周的对话记录看有哪些内容在反复向 Claude 解释——这些就应该写进模板看有哪些规则它老是触犯——这些就要把表述写得再明确一点。版本管理上我直接走 Git。个人模板放私有仓库团队模板放公共仓库每次改动配一条清晰的提交信息。这样谁动了什么规则、为什么动都有记录可查。模板有了版本历史之后出问题就能回滚改坏了也不怕。5.3 共享模板的几种姿势常见的共享方式有三种把模板仓库公开作为团队的 onboarding 材料新人来了先读一遍模板再开工用 git submodule 或 subtree 把模板目录挂进项目仓库一处更新、处处生效在内部文档站里维护一份模板的渲染版本方便非技术同学 review 规则。最推荐的是第二种模板目录作为独立仓库项目里用 submodule 引用。好处是模板改进可以一处更新、处处生效坏处是容易产生版本不一致。所以还要在 CLAUDE.md 顶部写清楚“模板版本号”方便排查问题时对齐。团队里有人反馈“Claude 好像不按规范来了”第一件事就是先对版本号。最后再分享一点个人体会写到这里说点实际感受。claude-code-templates 这套东西本质上是在给模型立规矩、划边界、攒经验。它不复杂技术含量也不算高但价值非常实在——它把每一次对话里你重复交代的信息、每一次 review 里你反复强调的问题都沉淀成了可复用的资产。我自己最深的感受是项目越往后模板带来的收益越明显因为它会跟着项目一起长把团队的约定、踩过的坑、积累的知识一点点固化进去。最后给一个建议不要一上来就搭一套大而全的模板。先写一个 20 行的 CLAUDE.md再加两个最常用的斜杠命令用一两周然后看实际对话哪里不顺手再迭代。模板是长出来的不是设计出来的。等它长到一定规模你自然会拥有属于自己团队的 claude-code-templates。