最近有个朋友跟我吐槽说 Claude Code 每开一个新会话都得先把项目背景、代码规范、测试命令重新念一遍稍微漏一句它就开始按自己的理解办事改出来的代码风格跟团队完全不在一个频道上。我听完只回了一句你缺的不是更好的模型是一套像样的模板。很多人把“claude-code-templates”理解成网上下载一个配置包拷进项目就完事。真正用起来你会发现模板这件事的本质是把那些“每次都要重复交代”的东西固化成文件让 Claude Code 第一次打开项目就能读到你的规矩、你的流程、你的禁区。这篇文章我想把这件事从头拆到尾CLAUDE.md 怎么写、slash command 怎么固化高频操作、脚手架模板怎么铺、settings.json 怎么配权限和 hooks以及模板这东西该怎么长期维护。适合两类人看一类是刚把 Claude Code 跑通、还在当聊天框用的新手另一类是已经用了两三周、但总觉得每次会话都在“重新调教”的老手。1. 先把概念捋清楚CLAUDE.md、slash command、脚手架各自管哪一段1.1 CLAUDE.md 是“人设”不是“任务清单”CLAUDE.md 放在项目根目录Claude Code 每次启动时都会自动读取它相当于给 AI 一个持久记忆。你可以把它理解成给新来的实习生做的一次性入职培训项目是干嘛的、代码放哪里、测试怎么跑、哪些雷不能踩讲一遍之后他后面干活就不用你反复提醒了。很多人的误区是把它写成任务清单比如“帮我加一个登录接口”“帮我写单元测试”。这完全反了。CLAUDE.md 应该描述的是“这个项目长期不变的上下文”不是某一次具体需求。我见过最离谱的写法是有人把某个需求的验收条件写进去结果下一个完全不相关的任务也被这些条件污染Claude Code 莫名其妙要求新功能也必须满足旧需求的行为。正确的 CLAUDE.md 应该包含这几类内容项目一句话定位这个服务是干什么的面向谁。常用命令本地启动、跑测试、跑 lint、构建给出确切命令别说“看 package.json”。技术栈和架构速览用了什么框架、目录怎么分层、数据流大致长什么样。代码约定命名规范、错误处理风格、禁止使用的模式。明确的不该做的事哪些操作会产生不可逆后果哪些文件不该手改。需要主动询问的场景比如涉及资金、迁移、删除数据时先列影响面再动手。哪怕只有这六条也能让 Claude Code 的行为质量提升一大截。你可以在对话里输入/init让它自动生成一版 CLAUDE.md但自动生成的版本通常偏保守、偏通用一定要自己过一遍把团队真正的规矩补进去。我自己每次新建项目都会在/init生成后花二十分钟手动改这一步省不了。1.2 slash command 把高频操作变成一句话CLAUDE.md 管“背景知识”slash command 管“动作”。它就是你敲一个斜杠命令比如/reviewClaude Code 就会自动执行你预先写好的那套检查流程。为什么需要它因为很多操作是“每次都要做、但每次都要重新描述”的。比如 code review你每次都得说“帮我看一下当前改动重点检查并发问题和边界情况别管格式”。这些话第一次说没问题第一百次说就很烦而且你每次说的细节可能还不一样Claude Code 的执行标准也跟着飘。把流程固化成一个/review命令它每次都会按同一把尺子干活标准就稳了。slash command 的文件放在.claude/commands/目录一个文件就是一个命令。文件名就是命令名比如review.md对应/review。文件本身是 Markdown在文件头部的 YAML 区域可以写描述正文里写你希望 Claude Code 执行的指令支持$ARGUMENTS变量把你在命令行里追加的参数传进去。这个机制非常轻但威力很大后面我详细拆。1.3 还有一类容易被忽略项目脚手架这是“模板”这个词最字面的意思。你接手一个新项目或者新微服务的时候是不是每次都要从零搭目录、配 lint、写 CLAUDE.md如果团队里有五个人各搭各的五份 CLAUDE.md 的规范可能都不一样Claude Code 在每个人的终端里完全不是一个性格。脚手架模板就是把“一套已经调教好的 Claude Code 工作环境”连同项目骨架一起复制过去让新项目从第一天起就继承团队积累的上下文。它不一定是复杂的代码生成器一个目录模板加一个脚本就够了。这个我放到第四部分细讲先把前面这两个核心机制讲透。2. 拆解一个最小可用模板仓库的样子2.1 顶层目录结构先看明白一个基础设施比较完整的 Claude Code 模板长这样my-project-template/ ├── CLAUDE.md ├── .claude/ │ ├── settings.json │ ├── commands/ │ │ ├── review.md │ │ └── commit.md │ └── skills/ │ └── db-review/ │ └── SKILL.md ├── .gitignore ├── Makefile └── README.md如果你的模板只打算管“AI 使用习惯”那CLAUDE.md加.claude/就够了如果还打算连项目骨架一起复制那就把Makefile、.gitignore、README.md这些也放进去。我个人建议模板里至少带一个Makefile或者等价的命令入口因为 CLAUDE.md 里写的“常用命令”必须指向真实存在的命令否则 Claude Code 读到了规矩但跑不通你反而会怪它笨。另外注意区分三层配置CLAUDE.md是项目级记忆~/.claude/CLAUDE.md是你个人的全局记忆.claude/settings.json是项目级行为配置。个人快捷键放全局团队规矩放项目别混在一起。混在一起的结果往往是你换台电脑全局文件没同步Claude Code 立刻“失忆”。2.2 CLAUDE.md 怎么写不该怎么写直接上一份可以抄的骨架这是我目前给后端 TypeScript 服务项目用的精简版# Order Service ## 我在这个仓库里做什么 这是一个订单领域的后端服务负责创建订单、支付回调、库存扣减。 整体是 TypeScript Fastify数据库用 PostgreSQLORM 是 Drizzle。 ## 常用命令 - 本地启动make dev - 跑全部测试make test - 跑单个测试npx vitest run src/orders/order.service.test.ts - lintmake lint ## 代码约定 - 业务代码禁止使用 any确实需要时用 unknown 加收窄。 - 所有数据库访问必须走 repository 层禁止在路由处理器里直接写 SQL。 - 外部 API 调用统一走 src/lib/http-client.ts超时时间 3 秒。 - commit message 用 conventional commits 格式。 ## 绝对不要做的事 - 不要修改 db/migrations/ 下已经执行过的迁移文件新增迁移用 make migration。 - 不要在响应里直接抛出内部错误堆栈。 - 不要缓存 getUserSession() 的结果用户状态可能随时失效。 ## 动手前先问我 - 涉及支付金额、退款、库存扣减逻辑的改动先列出影响面再写代码。 - 需要清表、批量更新数据的操作先确认有没有线上数据在跑。你看这份文档没有一句“请帮我实现 XX 功能”全部是长期稳定的上下文。但它已经足以让 Claude Code 在写代码前知道要守 repository 分层、不能用 any、不能动历史迁移文件、涉及资金要停下来问。这些恰恰是团队最容易在 code review 里反复强调的东西现在提前说好了。常见的反面典型有三种。第一种是写太长超过 500 行Claude Code 每次启动都要消费大量上下文反而冲淡重点真正关键的约定淹没在废话里第二种是写成“当前需求描述”比如把“这个月要做秒杀活动”写进去需求结束后文档就成了一堆僵尸指令第三种是把版本号、接口地址这类会频繁变动的信息写死在里面每次变更都要去改文档改不勤就出错。记住一句话CLAUDE.md 里只放“三个月后仍然成立”的东西。2.3 一份能直接抄的 CLAUDE.md 骨架上面那份就是骨架我再补充一个更普适的最小版适合各种语言和项目类型# 项目名 ## 定位 一句话说清楚这个仓库是干什么的。 ## 常用命令 - 安装依赖... - 本地开发... - 跑测试... - 构建/静态检查... ## 代码规范 3-5 条最核心的约定不要超过 10 条。 ## 禁区 列出可能导致事故的操作明确说“不要做 X”。 ## 架构速览 两三段话讲清楚模块边界和数据流配合关键目录路径。 ## 需要先问再做 列出高风险操作的触发对话比如数据迁移、批量发消息、改权限。这个骨架的妙处在于它天然限制了长度。每个板块都要求你写得非常克制逼你把真正重要的东西挑出来。写完之后你可以把它交给 Claude Code 做一次“体检”让它基于当前仓库的代码结构检查这份文档有没有遗漏关键目录、有没有写错命令。这一步我是强烈建议做的因为很多项目经过长期迭代实际结构和文档早就对不上了。3. 用 slash command 把你最高频的三件事固化下来3.1 自定义指令的存放位置和 YAML 头slash command 多数人用过内置的/compact、/clear这些但很少有人意识到.claude/commands/目录可以自定义。放一个review.md终端里敲/review就能触发。文件本身是 Markdown头部用 YAML 写描述正文就是指令。我实际在用的一个 review 命令长这样--- description: 对当前工作区改动做一轮严格 code review argument-hint: 可选补充重点关注项如 重点看并发和安全 --- 先运行 git diff HEAD 查看当前改动然后按下面的标准做 review 1. 逐文件指出逻辑错误、边界条件遗漏、并发安全问题。 2. 重点检查错误处理有没有吞异常、有没有在回调里抛异常。 3. 检查是否符合 CLAUDE.md 里的代码约定违反时明确指出来。 4. 如果改动涉及资金、库存、用户敏感信息必须列出具体风险点。 5. 不要泛泛而谈“代码质量不错”每个结论都要指向具体行号。 额外关注如果有$ARGUMENTS注意几个细节。第一我让它“先运行git diff HEAD”这是为了让 Claude Code 明确审查范围否则它可能只凭对话里的只言片语假装看过了第二我要求“每个结论都要指向具体行号”这个约束能显著抑制 AI 给出空泛的赞美第三$ARGUMENTS放在最后方便我临时追加关注点比如/review 重点看缓存一致性和分布式锁就能传入去这个设计很关键。3.2 实操一让 Claude Code 完成一次“有脾气”的 review把上面那份文件存到.claude/commands/review.md之后你在终端敲/review它就会老老实实跑一遍。但我建议你第一次用的时候故意让它 review 一段你已知有问题的代码测试它有没有真的按你的标准执行。我见过很多人写完命令就以为万事大吉结果 Claude Code 给出一堆“代码风格良好”的废话问题全是自己 review 出来的。如果发现它没按标准来多半是命令写得不够具体。比如“注意边界情况”这种话太虚要改成“检查数组为空、数值溢出、并发覆盖三类情况”。AI 对模糊指令的执行方差很大你把检查项变得可验证输出质量才会稳定。3.3 实操二按团队规范生成 commit messagecommit message 是另一个非常适合固化的场景。团队规范往往是一大段 Markdown里面有格式要求、有 emoji 惯例、有 ticket 号规则。与其每次手动让 Claude Code“按规范写”不如做一个/commit命令--- description: 根据暂存区改动生成符合规范的 commit message argument-hint: 可选补充改动背景如 修复了超时未释放连接的问题 --- 先运行 git diff --cached 查看暂存区改动再读 .claude/commit-style.md 中的规范按规范生成 5 个候选 commit message。 要求 1. 格式严格遵守 .claude/commit-style.md。 2. 每个 message 必须概括实际改动禁止编造细节。 3. 若有 ticket 号放在 subject 末尾。 4. 最后用 git diff --cached --stat 核对一遍改动范围避免漏掉文件。 补充背景可选$ARGUMENTS注意到我把提交风格规范单独放在.claude/commit-style.md而不是写死在命令文件里。为什么因为规范的变更频率高于命令本身拆开之后团队调整格式只需要改一个文件不用动命令。这就是“模板的模板”思想把稳定的流程和易变的规则分离。3.4 为什么我只推荐先做三个很多人一上手就想把所有的操作都做成命令我劝你克制。我的经验是第一轮只固化和“代码审查”、“提交信息”、“启动测试”相关的三个命令就够。理由很简单每个 slash command 都是一次决策的固化做多了不仅维护成本高而且你自己都记不住有哪些命令最后全变成僵尸文件。什么样的任务适合做成命令三个特征高频、流程稳定、需要按 checklist 执行。比如 review 和 commit 就非常典型每次都要做、每次流程都一样。反过来那种“帮我想想这个 bug 可能的原因”的探索型任务就不适合做命令因为它本质是开放式的固化之后反而限制发挥。4. 把模板仓库变成脚手架快速起一个新项目4.1 脚手架的标准内容CLAUDE.md 和 slash command 解决的是“已有项目怎么用”的问题脚手架解决的是“新项目怎么起”的问题。我在模板仓库里会放一套“最小可运行”的项目骨架里面除了常规代码最重要的就是带好配置的.claude/和一份针对该项目类型优化过的 CLAUDE.md。脚手架和普通代码模板的区别在细节。普通模板给你一个空 README、一个 hello world脚手架则会在 CLAUDE.md 里预先写清楚这类项目的君规。比如创建 TypeScript 后端服务时CLAUDE.md 里直接就有“路由层不写业务逻辑”“校验用 zod”“所有环境变量必须经过 config 模块”这些约定。这样你新建的每个服务Claude Code 从一开始就知道该按什么风格写代码。4.2 一个小脚本让模板自动铺开最简单的脚手架脚本一句复制加一个变量替换就够。我写过一个粗糙但够用的create_project.sh#!/usr/bin/env bash set -euo pipefail PROJECT_NAME${1:-my-app} TEMPLATE_DIR$(dirname $0)/../templates/backend-ts DEST_DIR./$PROJECT_NAME if [ -d $DEST_DIR ]; then echo 目录已存在$DEST_DIR exit 1 fi cp -R $TEMPLATE_DIR $DEST_DIR # macOS 用 sed -i Linux 用 sed -i if [[ $(uname) Darwin ]]; then sed -i s/{{PROJECT_NAME}}/$PROJECT_NAME/g $DEST_DIR/CLAUDE.md else sed -i s/{{PROJECT_NAME}}/$PROJECT_NAME/g $DEST_DIR/CLAUDE.md fi echo 项目已创建$DEST_DIR对应的 CLAUDE.md 模板里写## 定位\n这是 {{PROJECT_NAME}} 服务的仓库...脚本把占位符替换成真实项目名。这个脚本没有任何依赖不需要装 Yeoman、不需要装 cookiecutter丢在任何机器上都能跑。这里刻意不做复杂功能是因为脚手架的价值在于“快速铺开标准”而不是搞成一个配置系统。等团队真需要参数化选型的时候再考虑引入更重的生成器不迟。4.3 从“单个项目模板”到“团队模板”模板仓库在团队里真正生效靠的是把它当成代码一样维护。我的做法是模板单独放一个 git 仓库每次有人踩了新坑、总结出新的规范就提交一条记录到模板仓库然后所有新项目都从最新模板创建。这样团队踩坑的集体记忆会逐步沉淀到每一份新项目的 CLAUDE.md 里而不是散落在各人的聊天记录中。这一步的价值很容易被低估。单个模板顶多算个人效率工具一旦团队共同维护它就成了组织的“操作手册”。我见过一个团队三个月内把 CLAUDE.md 从 20 行养到 120 行每一条都是实际事故换来的教训之后 Claude Code 在项目里犯错的比例肉眼可见地下降。这事不需要什么高级平台一个 git 仓库、一次 code review 就够了。5. .claude/settings.json 里值得抄走的安全配置5.1 权限白名单不是束缚是保护模板里除了 CLAUDE.md 和 commands还应该有一份.claude/settings.json。很多人完全不配这个文件让 Claude Code 每次操作都弹权限确认或者干脆全部放行。我的建议是配一个“默认允许 明确禁止 部分询问”的三层权限。下面这份是一个实际可用的基础配置{ permissions: { allow: [ Bash(make *), Bash(npm run *), Bash(pnpm *), Read(.env.example), Edit(config/**) ], deny: [ Bash(rm -rf *), Bash(git push --force), Edit(db/migrations/**) ], ask: [ Edit(*) ] } }注意这里的关键思路把安全的常规操作放进 allow把可能有破坏性的操作放进 deny剩下的再 ask。如果不写 denyClaude Code 对危险命令只会弹窗询问手一抖就放行了如果写了 deny它连问都不问直接拒绝等于上了一道保险。Edit(database/migrations/**)禁止改动迁移文件这一点尤其有用配合前面 CLAUDE.md 里的“绝对不要做”双保险才靠谱。5.2 hooks让工具自动完成脏活settings.json 里的 hooks 是另一个高价值功能在特定事件发生后自动执行命令。我用的最顺手的一个场景是自动格式化。每当 Claude Code 编辑了 TypeScript 文件就自动跑一遍 eslint 修复{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: bash -c if echo \$CLAUDE_FILE_PATHS\ | grep -q \\\.ts$\; then npx eslint --fix $CLAUDE_FILE_PATHS; fi } ] } ] } }这样做的价值在于每次 AI 改完代码格式问题立刻被自动修正最后 diff 干净得多。$CLAUDE_FILE_PATHS是 hook 环境变量里提供的被操作文件列表这个变量名要记牢调试 hook 时全靠它。不过 hooks 的坑也不少。一是它同步执行如果命令很慢每次工具调用都会被拖住整个会话会变得非常卡。二是容易形成死循环hook 改文件文件变更再触发 hook。所以 hook 命令里一定要做好幂等保护和范围控制能不加就不加。5.3 一个容易踩的坑hook 权限互相打架我实际踩过的一个坑是给 hook 配了npx prettier --write但 settings 的deny里写了Bash(npx *)导致 hook 命令跑不了而且 Claude Code 还不会明确告诉你失败原因只会在日志里静默跳过。排查半天才反应过来是权限配置把 hook 拦截了。所以配 hooks 和权限时一定要互相照看。凡是 hook 里要执行的命令权限策略里要给对应的 allow不能一边让 hook 跑命令一边 deny 同类命令。如果 hook 静默失败打开claude --debug重跑一次基本都能在日志里看到是哪一步被权限拦截。这条经验我建议直接写进模板的 README 里免得下一个人再踩一遍。6. 模板维护写一次不难难的是每天跟着项目进化6.1 什么时候该改模板模板不是写完就冻结的。我给自己定了一个“两次原则”同样的问题如果发生了两次就必须回模板里找原因、补规则。比如 Claude Code 连着两次在某个仓库里用了不存在的测试命令那说明 CLAUDE.md 的命令写法有问题不是说教它一次就完。识别信号其实很直观。第一种信号是“你又重复交代了”你发现自己在新会话里反复强调同一句话这句话就该进模板。第二种信号是“错误模式复现”同一个坑踩第二次说明模板里缺了对应的禁区。第三种信号是“文档和现实脱节”测试框架从 vitest 换成了 jest但 CLAUDE.md 还写着旧命令这时候不是项目错了是模板欠维护了。6.2 我维护模板的两个小习惯第一个习惯是把模板的更新当成 commit写清楚改动原因。这样三个月后再看模板的演进历史能清楚知道每条规范是为了防什么坑加进来的而不是看到一句没头没尾的“不要用 X”干瞪眼。我在模板仓库里专门建了UPDATES.md记录这类变更成本极低收益很大。第二个习惯是分层维护。个人偏好放在全局~/.claude/CLAUDE.md团队规范放在项目 CLAUDE.md两类内容严格分离。如果你只有一个人用可以偷懒合并但只要涉及协作分层就很有必要——不然每次同步团队模板时都会带着你个人的快捷键习惯到处跑反而干扰。另外如果 CLAUDE.md 越来越长我建议用import把内容拆成多个文档比如ARCHITECTURE.md、TESTING.md在主文件里引用。这样既保持主文件精简又不会丢细节。很多新版 Claude Code 都支持这个引用语法具体查一下官方文档就行。6.3 最后一点别为了模板而模板老实说模板这东西是有边际效应的。配到一定程度再叠更多的规则、更多的 hook收益就开始下降甚至会让 Claude Code 的行为变得僵化。我见过一些重型模板光 settings.json 就三百行结果 AI 的每一次操作都在和各种规则的夹缝里打架最后用户反而觉得它“变笨了”。我自己现在的状态是一个项目里通常就一份 80 到 150 行的 CLAUDE.md、三个 slash command、一份精简的 permissions、一个自动格式化 hook。不多不少刚好覆盖这个项目 80% 的重复劳动。剩下的那些一次性的、探索型的问题本来就是需要人和 AI 临场沟通才能处理好的强行走流程反而适得其反。结尾想分享一个体会模板的价值不在“配置有多全”而在“该有的都有、不该有的绝对没有”。每一条规则都要能回答“这条是为了防止哪次事故”这个问题如果答不上来就大胆删掉。顺手分享一个我现在每天都在用的小技巧任何一次成功的对话如果里面的指令写得特别好、特别清晰我会花一分钟把它抽出来变成 slash command 存起来。做完 review 之后发现哪个检查项特别有效就补进 review 命令里。模板不是设计出来的是长出来的。你喂养它的每一次教训都会变成下一次会话里的默认行为。这大概就是 Claude Code 从“偶尔惊艳的工具”变成“稳定可靠的队友”之间最值得投入的那件事。