如果你长期用 Claude Code 帮自己写代码大概率会经历这么一段渐变一开始只在终端里临时提问后来把常用规范塞进 CLAUDE.md再后来发现每开一个新项目都要重新写一遍同样的东西。我就是在复制了七八次同一份 CLAUDE.md 之后被这种重复劳动烦得不行才开始动手整理 claude-code-templates 这套东西。它本质上不是某个固定产品而是一套能让 Claude Code 的行为跨项目保持一致的方法论和工程结构把“调教 AI 的成本”从每个项目里剥出来变成一次性投入、持续复用的模板资产。这篇文章我会把它拆开讲清楚一套可用的 Claude Code 模板应该包含哪些文件、每个文件解决什么问题、怎么写才不会被模型忽略以及我自己在维护和迁移模板时踩过的那些坑。不管你之前只是听说过 CLAUDE.md还是已经在项目里用了一段时间但总觉得不好使这篇都适合你。1. 整体架构与工作流设计为什么模板要从项目里单独拆出来1.1 先把问题说清楚每开一个项目你都在重复“调教”成本用过 Claude Code 的人都有感触它对项目上下文的理解很大程度上依赖于你喂给它的指令和约定。同样一个“帮我写接口”在熟悉的代码库里它可以准确按你的分层规范生成换一个没写过约定的仓库它大概率会按自己最习惯的方式自由发挥然后再被你反复纠正。我早期就是吃了这个亏。每个新项目都从零开始写一份 CLAUDE.md把常用的命令、目录规范、禁止触碰的文件、代码风格一条条列出来。项目少的时候还好等到同时维护三四个不同技术栈的仓库我发现自己每次都在复制粘贴和重新修改之间浪费时间而且改着改着版本还对不上了。真正让我下决心做 claude-code-templates 的是一次把旧模板复制到新项目时发现里面的命令路径写死导致 Claude 调了一个根本不存在的脚本我花了半天才找到原因。把模板从项目里单独拆出来带来的直接好处有三个。第一是版本管理你可以用 Git 跟踪每一份模板的变更改动可回溯而不是散落在各个仓库里没人管第二是团队共享新成员只需要把模板拉下来配好就能获得和你完全一致的 AI 协作规范不用靠口口相传第三是批量更新你优化了某个命令的写法只需要改模板仓库然后让现有项目重新同步即可而不是跑到每个仓库里去手动改一遍。1.2 一套最小可用的模板至少包含五部分我在长期使用中把模板沉淀成了五个核心部件它们各管一段组合起来才能让 Claude Code 稳定、可预测地工作CLAUDE.md这是 Claude Code 的项目“记忆”入口负责告诉模型这个项目是什么、代码该怎么写、有哪些红线。它的优先级最高所以也是模板的必选项。.claude/commands/自定义斜杠命令比如 /lint、/test、/docs。本质是把你的日常巡检指令固化成一段可复用、可带参数的命令避免每次手打一大段 Prompt。.claude/agents/子代理定义比如专门管数据库迁移的、专门管前端样式的。每个代理可以有独立的工具权限和上下文让 Claude 在碰到专项任务时自动调用更专业的“分身”。.claude/hooks/钩子脚本在特定事件发生前后自动触发比如提交代码前自动跑格式化、收到错误输出后自动拉取日志。这是把规范“强制化”的关键。.claude/settings.json模型参数和权限配置比如默认模型版本、是否允许 Claude 自动执行命令、工具白名单等。这五部分不是必须一次配齐。如果你刚开始接触我的建议是先只做 CLAUDE.md 加 commands 两层等跑顺了再引入 agents 和 hooks。因为后两者会直接涉及文件系统和外部命令的自动执行一旦配置不当影响面比单纯写一段提示词大得多。1.3 不同技术栈的模板划分策略模板要真正好用就不能所有项目共用一份。我目前的做法是按技术栈维护三套主模板每一套内部再通过变量区分具体项目类型。这里的关键不是“模板越多越好”而是找到一个合适的粒度让公用的逻辑尽量共用差异化的部分靠变量注入。项目类型模板侧重点典型自定义命令推荐代理Node.js/TypeScript 全栈目录边界、ESLint/Prettier 规范、Prisma/ORM 约定、测试策略/init、/generate-module、/testbackend-agent、frontend-agentPython 数据类项目虚拟环境、依赖管理、notebook 与脚本的边界、pytest 规则/venv、/migrate、/benchmark>--- description: 生成一个新的业务模块包含 service、controller 和单元测试骨架 argument_hint: module_name allowed-tools: Bash(Write), Read, Edit, Write(File) --- 根据用户提供的模块名 % args.module_name %按以下约定生成代码 1. 在 src/modules/% args.module_name % 下创建目录结构包含 service.js、controller.js、routes.js。 2. 每个文件顶部必须加上业务模块注释注明创建日期和用途。 3. 在 tests/unit/ 下生成对应的测试文件测试用例至少覆盖正常路径和错误路径。 4. 生成完后运行 npm run lint 检查新生成的代码发现问题立即修复。 5. 结束前输出完整的文件清单并说明每个文件的职责。这里有几个细节值得展开。description一定要写成“能做什么事”而不是“模板文件”因为 Claude 在会话中是根据语义来检索命令的太泛的描述会让它找不着。argument_hint是给用户看的输入提示配合前端自动补全体验会好很多。allowed-tools则是我强烈建议你写清楚的字段它限定这条命令执行时能用哪些工具避免命令里触发 Claude 去调用网络服务或者修改范围之外的文件。很多模板执行出错都是因为 allowed-tools 留空导致默认权限过大。另外命令正文里我刻意用了% args.module_name %这样的模板语法而不是让 Claude 自己猜模块名。这种参数化写法极大提高了命令的可复用性同一个文件在任意项目里都能用。熟练之后你还可以在命令里嵌套条件判断比如检测到项目是 TypeScript 就生成.ts文件否则生成.js文件。2.3 子代理给你的 AI 装上不同专业的“外挂大脑”只用一个全局 Claude 做所有事情效率其实不高。比如你在写 Go 后端Claude 需要同时理解 Kubernetes 配置、前端接口、数据库 schema上下文很快就会打架。引入 agents 子代理相当于把不同领域的知识拆开存放让主 Claude 遇到特定问题时调派对应代理来处理。我模板仓库里最常用的一份子代理定义长这样--- name: database-agent description: 负责数据库 schema 设计、迁移脚本生成和查询性能分析。当任务是修改表结构、编写 migration 或排查慢查询时调用。 tools: Read, Edit, Bash(Read), Bash(Write) --- 你是团队的数据库专家。你只负责与数据库相关的任务不要参与业务代码开发。 工作时必须遵守 - 修改 schema 前先检查现有 migrations 目录保证迁移脚本是按时间顺序命名。 - 所有 SQL 必须附带索引分析和执行计划说明。 - 禁止直接在生产环境执行写入类 SQL只允许输出待人工审核的脚本。 - 碰到不确定的字段含义先阅读 models/ 下的注释文档不要自己臆测。这个文件放在.claude/agents/database-agent.md下即可被识别。 它的价值在于当主 Claude 收到“给 users 表增加一个 last_login 字段”这类请求时会自动判断这属于数据库任务于是把工作转交给 database-agent后者带着它自己的专用规则和工具权限去执行而不是用全局上下文里那些泛泛的代码规则。这样设计能让上下文更干净也让安全边界更清晰。你需要重点设计的是 tools 字段。我给数据库代理只开放了文件的读和写权限以及 Bash 的只读和只写接口不允许执行任何删除操作。工具的颗粒度直接影响子代理能造成的影响范围宁可先收紧碰到需求再放开也不要一上来就全放。3. 从零搭建一套可直接复用的模板实操记录3.1 模板仓库的目录结构到底怎么摆纸上谈兵讲完概念接下来我把一套我实际在用的模板仓库完整摆出来。它不需要多复杂关键在于结构清楚任何人拉下来之后都能一眼看出什么文件是干什么的。claude-code-templates/ ├── README.md ├── common/ │ ├── style.md # 通用代码规范和红线 │ └── commands.md # 通用命令速查片段 ├── node-fullstack/ │ ├── CLAUDE.md # 主模板会引用 common 下的片段 │ ├── .claude/ │ │ ├── commands/ │ │ │ ├── dev.md │ │ │ ├── lint.md │ │ │ └── generate-module.md │ │ ├── agents/ │ │ │ ├── backend-agent.md │ │ │ └── frontend-agent.md │ │ ├── hooks/ │ │ │ ├── post-start.sh │ │ │ └── pre-commit.sh │ │ └── settings.json │ └── scripts/ │ └── post-create.sh # 项目创建后执行的初始化脚本 ├── python-data/ │ ├── CLAUDE.md │ └── .claude/... └── scaffold.sh # 通用脚手架入口用来从模板创建新项目这个布局的核心思想是common/放跨项目复用的共性内容每个具体模板目录仅保留与自己技术栈强相关的部分。scaffold.sh是统一入口后面我会详细讲它怎么工作。3.2 初始化脚本一句命令把一个模板变成真实项目模板仓库写的再漂亮如果复制过程全靠手动用两次你就会放弃。所以我在仓库根目录放了一个scaffold.sh负责把模板内容复制到新项目目录同时用变量替换手段把模板里的占位符替换成目标项目的信息。脚本不必复杂但必须稳定、可预期。这是我的简化版本你可以直接抄按自己需要改变量名就行#!/usr/bin/env bash set -euo pipefail TEMPLATE_NAME${1:?用法: ./scaffold.sh template_name project_dir} PROJECT_DIR${2:?需要传入项目目标目录} PROJECT_NAME$(basename $PROJECT_DIR) if [ ! -d $TEMPLATE_NAME ]; then echo 模板 $TEMPLATE_NAME 不存在可选模板node-fullstack, python-data exit 1 fi echo 开始创建项目 $PROJECT_NAME使用模板 $TEMPLATE_NAME ... cp -R $TEMPLATE_NAME $PROJECT_DIR cd $PROJECT_DIR # 把 CLAUDE.md 里的项目占位符替换为真实项目名 sed -i.bak s/__PROJECT_NAME__/$PROJECT_NAME/g CLAUDE.md sed -i.bak s/__PROJECT_NAME__/$PROJECT_NAME/g .claude/settings.json # 清理临时文件 find . -name *.bak -delete echo 项目创建完成。下一步 echo 1. cd $PROJECT_DIR echo 2. 阅读 CLAUDE.md 并调整项目技术栈描述 echo 3. 在项目里运行 claude 开始使用写这个脚本时有三个细节值得提醒。第一set -euo pipefail一定要加否则某个命令出错脚本会继续往下跑最后产出一个残缺项目排查起来很痛苦。第二我用的是sed -i.bak做替换同时把替换后的残留文件清理掉这样即使用户的 sed 版本在 Linux 和 macOS 上有差异也不容易踩坑。第三脚本执行完不要直接帮你打开 Claude而是打印下一步提示因为你作为开发者需要先浏览一遍模板内容确认技术栈描述是否准确盲信模板本身就是隐患。3.3 实操现场把一个模板跑通全流程为了让你更直观看到效果我以node-fullstack模板为例完整跑一遍从模板到可用项目的流程。假设我准备新写一个叫order-service的微服务项目第 1 步执行./scaffold.sh node-fullstack ./order-service脚本会在 order-service 目录下生成完整的 CLAUDE.md 和 .claude 目录。第 2 步我打开 order-service/CLAUDE.md把项目描述从“全栈商城脚手架”改成“订单领域微服务只负责订单创建、状态流转和查询”并补充依赖的外部服务地址说明。第 3 步我在 order-service 里初始化实际代码仓库执行git init然后把模板生成的 .gitignore 看起来没问题后提交一次初始 commit。第 4 步在项目根目录运行claude进入对话后直接输入/init让 Claude Code 基于当前目录结构二次生成/校验 CLAUDE.md这一步能把刚才手动修改的内容和实际文件结构对齐。第 5 步测试自定义命令是否生效输入/generate-module payment正常情况下它会按照模板里的约定自动创建 payment 模块及测试文件结束后打印文件清单。第 6 步如果这个项目后续要提交协作我会把模板里的.claude/settings.json确认一遍确保其中有“禁止自动执行破坏性命令”的开关再推送到远程仓库。这套流程跑下来一个可用的 AI 协作项目就诞生了全程大概不到十分钟。相比我以前手动复制 CLAUDE.md、再逐个创建命令文件的老办法节省的不仅是时间更重要的是出错率明显下降因为有血缘关系的模板意味着行为可预期。3.4 用户级、项目级、目录级三层配置怎么分Claude Code 的配置天然分为几个层级决策路径大致是越靠近当前目录的配置越优先。我实际使用中会刻意利用这个特性而不是把所有东西都塞到一个文件里。最外层是用户级配置放在~/.claude/CLAUDE.md我只写与具体项目无关的个人偏好比如“我偏好函数式写法”“不要在提交信息里使用 emoji”“遇到不确定的需求先列问题清单”。 中间层是项目级 CLAUDE.md放本项目独有规则比如“不要修改 legacy 目录”“部署分支是 main”。 最内层是目录级 CLAUDE.md一些大型 monorepo 里我会在子模块目录单独放一个 CLAUDE.md只描述该模块的职责和例外规则。这套分层设计最直接的效果是同一个模板可以复制给不同的仓库而不需要全部重写因为用户级的偏好会被自动继承项目级只覆盖必改部分目录级只描述例外。配置覆盖面更自然模板的普适性也更强。4. 避坑实录与常见问题排查4.1 模板复制过去了但 Claude 完全不按模板执行这是最多人遇到的问题。排查思路其实不复杂优先按下面几步来确认文件路径正确。Claude Code 默认只读项目根目录下的 CLAUDE.md 和.claude/目录如果你把配置放到了docs/或者子目录里它根本不会加载。确认没有语法破坏。CLAUDE.md 如果包含了无法解析的代码块或路径Claude 可能会跳过部分内容。可以执行/status或用编辑器检查文件的 YAML Frontmatter 是否闭合。确认不是被 hooks 干扰。有些 hook 会在会话启动时改写 CLAUDE.md 或者把它的内容替换成另一个版本这种问题最难察觉需要你检查.claude/hooks/下有没有相关脚本。最后验证你是在正确的仓库根目录启动的 Claude。很多项目都有嵌套目录在子目录启动时父级的 CLAUDE.md 优先级会下降导致行为和你预期不符。我自己曾经在 monorepo 里吃过这个亏明明根目录 CLAUDE.md 写得明明白白“不要触碰 worker 目录”还是在 worker 子目录里启动了交互式命令结果模型完全无视了那条规则。后来才意识到子目录里的目录级配置是空的反而给了模型“自由发挥”的空间。4.2 模板开始生效之后上下文怎么还是两三轮就满模板里配置内容过多是上下文快速耗尽的头号原因。很多人有一个误解以为 CLAUDE.md 越详细越好实际上 Claude Code 在启动会话时会把模型需要的大部分上下文装进窗口你把上千行规范全塞进去等于把原本用于处理代码的空间挤掉了。我的经验是CLAUDE.md 控制在 200 到 400 行为宜。超出的部分应该单独放在 docs 或 templates 文件夹里然后用一行“CLAUDE碰到问题时先读 docs/xxx.md”来引导。另一个技巧是把大段低频规则从 CLAUDE.md 移到 commands 里比如“如何生成迁移脚本”这样只在特定操作时才需要的知识写成/migrate-hint命令用时才加载不用时完全不占上下文。另外在.claude/settings.json里可以设置自动压缩阈值我一般会配置成“会话接近上限时自动执行 compact”避免对话进行到一半突然因为超限而丢失中间的约定。这是一个看着不起眼但实际体验提升极大的设置。4.3 Hook 脚本一跑就出问题甚至会递归触发Hooks 是模板里最容易引发事故的环节。我见过最典型的翻车现场有人写了一个 pre-commit 的 hook里面调用了 ESLint 并自动修复代码但修复后的代码又触发了另一个 hook 去重新检查于是两个脚本互相调用终端被刷屏最后只能强制结束。你现在项目里用 hooks 的话务必遵循三条原则第一hook 内不要调用会触发其他 hook 的命令如果必须调用请在脚本开头设置环境变量跳过第二hook 的日志必须单独输出到文件这样排查时能看到 step by step 的执行记录第三hook 执行时间要有限制比如超过 10 秒即中断防止死循环把整个终端卡住。我模板里提供的pre-commit.sh只有十几行它只做两件事格式化新增文件、跑一遍语法校验并且把输出写到.claude/hooks/logs/pre-commit.log。这样一旦发生问题我打开日志文件就能知道是哪一步失效而不是对着黑屏干瞪眼。4.4 权限白名单太宽Claude 动不动就自己删文件这个问题在模板初期最容易出现。因为默认配置下Claude Code 能执行很多命令如果你在 setting.json 里没有限制模型一旦判断“文件不需要了”可能就直接执行删除。我早期就让它误删过一次本地未提交的 notes 目录从那次之后我对权限收紧到了偏执的程度。当前模板里 settings.json 的权限参考如下{ permissions: { defaultMode: plan, allow: [ Bash(npm run lint), Bash(npm test), Bash(git status), Bash(git diff), Edit(File) ], deny: [ Bash(rm *), Bash(git push --force), Bash(dropdb) ], ask: [ Bash(git commit), Bash(git push), Edit(Write) ] }, model: claude-sonnet-4-20250514, autoCompactEnabled: true }这个配置的核心思路是默认模式用 plan让 Claude 先给出执行计划而不是直接动手只有我们明确允许的命令能够直接执行写入操作进入 ask 模式需要人工确认。你可能有自己的偏好但原则是宁严勿松。模板的价值在于可复用如果模板自带宽松权限那它反而不是资产而是未来每个项目的风险源。5. 基于实际项目回调的几条经验踩过足够多坑之后我对 claude-code-templates 这类东西的定位有了更清晰的认知。它不是一锤子买卖不是写完一套模板就永远不用管了。AI 模型在迭代项目的目录结构在演进你最常用的代码风格也会変所以模板需要像普通代码库一样定期维护。我的做法是每两周留出一点时间把正在进行的项目里发现的规则差异回写到模板仓库相当于把“运行时的经验沉淀”自动回流到起点。这个循环一旦跑起来你会发现模板越来越贴近你真实的工作方式而不是一开始拍脑袋写出来的理想化规则。另一个感想是模板一定要为“人”留出干预空间。我看过有些人把模板做成了无比庞大的自动化工坊希望 Claude 从头到尾不需要人工确认。实际上越复杂的自动化越脆弱一旦中间路径变了后面全链路的输出都会跟着错位。所以我所有模板里都会刻意保留一些需要人工 review 的 checkpoint比如命令执行前打印详细计划、迁移脚本只生成不执行。这不是对 AI 能力的不信任而是对复杂性的敬畏。如果你也想做一套自己的 Claude Code 模板我的建议是从最小结构开始一份 CLAUDE.md、一条自定义命令、一个 settings.json先把三层配置的关系跑通再逐步加 agents 和 hooks。不用一开始就追求大而全因为模板真正的价值不是“功能多”而是“复用起来不费劲”。等某一天你新开项目跑完 scaffold 脚本直接进入开发状态的时候就会明白这种前置投入有多划算。