如果你也跟我一样，每天要在终端里打开 Claude Code 处理很多不同类型的任务，你迟早会发现一件事：同一个项目反复解释同样的事情，效率太低了。我一开始也是靠复制粘贴历史对话来维持一致性，后来实在受不了，才动手整理了一套自己的claude-code-templates。这套模板体系说白了就是 Claude Code 的“团队手册 + 自动化脚本库”，把项目规则、常用命令、钩子检查、角色分工都固化下来，让我不用每次开口前先把背景讲一遍。
这篇文章就围绕我维护的这个模板库展开，聊清楚它解决了什么问题、里面每个组件到底怎么用、我是怎么从零搭起来的，以及踩过的几个实实在在的坑。如果你已经在用 Claude Code，或者正准备把它引入团队，这套东西可以直接拿去改着用。
1. 先想清楚：Claude Code 模板到底在解决什么问题
1.1 没有模板时，我的工作流是什么样
在用模板之前，我的工作流可以用“每次都是开荒”来形容。新建一个项目，先在对话里贴一大堆背景说明：技术栈是什么、目录结构怎样、代码规范有哪些、测试命令怎么跑、哪些文件和目录绝对不能动。第一轮对话基本就是在做“入职培训”，真正开始写代码已经过了十几分钟。
更头疼的不是慢，而是不稳定。同一个任务，上午让 AI 做，它记得要跑 lint；下午换个会话再让它做，它可能就直接跳过检查，给出一个风格完全不同的实现。项目一多，这种行为漂移会被无限放大——你根本没法保证它在 A 项目和 B 项目里遵循同一套规范。
当时我就在想，Claude Code 本身提供了CLAUDE.md和.claude目录这些配置能力，但我每次都要从头写。与其重复劳动，不如把这些内容沉淀成一套可以复用、可以分享、可以迭代的模板。于是claude-code-templates这个仓库就建起来了。
1.2 claude-code-templates 的核心设计思路
这个模板库不是简单放几个配置文件，它的设计思路分了三层：
- 配置层：项目级的
CLAUDE.md、全局的~/.claude/CLAUDE.md，定义 AI 的“世界观”和行为底线。 - 能力层：
commands自定义命令、agents子代理、skills技能模板，给 AI 提供可复用的“工具箱”。 - 自动化层：
hooks钩子，在 AI 调用工具的关键节点上插入强制检查，保证流程不被跳过。
这三层有个好处：互不干扰，又层层递进。配置层管“该怎么做”，能力层管“能做什么”，自动化层管“必须怎么做”。任何一个项目进来，只要套上这套模板，AI 的行为就能稳定在一个预期范围内。
我特别看重一个指标：从打开终端到 AI 开始干活，能不能压缩到 30 秒以内。现在的效果是，新项目复制模板、改两个变量、启动会话，CLAUDE.md 自动加载，AI 已经知道技术栈、命令和规范，我可以直接说“帮我加一个用户登录接口”，剩下的细节它自己会从模板里找。
1.3 一个模板库的整体目录结构
我最终整理出来的目录长这样：
claude-code-templates/ ├── CLAUDE.md # 项目级主配置模板 ├── .claude/ │ ├── settings.json # 本地设置（hooks、权限） │ ├── commands/ # 自定义斜杠命令 │ │ ├── review.md # /review 代码审查 │ │ ├── commit.md # /commit 规范化提交 │ │ └── task.md # /task 拆解任务 │ ├── agents/ # 子代理模板 │ │ ├── backend.md │ │ └── frontend.md │ ├── skills/ # 技能模板 │ │ └── refactor/ │ │ ├── SKILL.md │ │ └── PROMPT.md │ └── hooks/ # 钩子脚本与配置 │ └── post_tool_use.sh └── templates/ # 新项目脚手架 ├── backend/ ├── frontend/ └──># 项目概览 - 定位：用户行为分析 API 服务 - 技术栈：Python 3.11 / FastAPI / PostgreSQL / Redis - 入口：app/main.py - 测试：pytest tests/ -q # 编码约定 - 所有接口返回结构统一为 {"data": ..., "error": ...} - 数据库迁移文件必须放在 migrations/versions/ - 禁止直接修改 auth/service.py 的认证逻辑，如需修改先说明原因 # 通用流程 1. 修改代码前先运行 `make lint` 确认当前基线 2. 实现功能后补充至少一条测试 3. 提交前运行 `make test`，确保全绿为什么强调控制篇幅？因为 Claude 的上下文窗口是有限的，你把 500 行的规范塞进去，它想找关键信息时反而会被噪声干扰。把规则压缩成“高信噪比”的条目，比穷举所有情况要有效得多。等 AI 遇到模板没覆盖的边界情况，我再把结论反哺回模板，形成迭代。
2.2 自定义命令：把高频操作变成斜杠命令
claude-code-templates里最常用的一层是commands。Claude Code 支持把.claude/commands/下的 Markdown 文件变成斜杠命令，输入/commit就会把文件内容注入当前对话，相当于预先写好的高质量提示词。
我的第一个自定义命令是/review，用来做代码审查。这个命令的核心价值是把“审查标准”固化成模板，包括安全审查、异常处理、日志规范、性能隐患等维度，不会因为 AI 当天状态不好而漏掉某类问题。文件内容大概是这样：
你是资深代码审查专家。请审查当前分支的改动，严格按以下维度输出结果： 1. 安全性：是否存在注入、越权、敏感信息泄漏风险 2. 健壮性：异常分支是否处理完整，有无隐藏的空指针或类型问题 3. 可维护性：命名是否清晰、函数是否过长、有无重复代码 4. 性能：是否存在不必要的循环、查询或资源未释放 每个问题标明文件与行号，按严重程度排序。如果没有问题，明确说“通过”。除了 review，我还定义了/task（把需求拆成可执行子任务）、/commit（按约定格式生成提交信息）、/fix（带上报错信息自动定位修复）。这些命令有一个共同点：把 AI 的输出格式和思考路径提前约束好，而不是让它自由发挥。
自定义命令里还可以用$ARGUMENTS接收对话里的参数。比如我在/task文件里写“请把以下需求拆解成子任务：$ARGUMENTS”，使用者在对话里输入/task 实现一个导出功能，后面那段文字就会自动填充进去。这个技巧非常实用，等于给命令做了一层“函数参数化”。
2.3 Hooks：在关键节点插一脚
如果说 CLAUDE.md 是“软约束”，那 hooks 就是“硬约束”。Claude Code 提供了事件钩子机制，能在 AI 调用工具之前、之后，或者一轮对话结束时执行脚本。我把模板库里的 hooks 分成两类：
- PreToolUse：在工具执行前拦截。比如禁止 AI 直接删除文件、禁止在
node_modules里搜索、禁止访问环境变量文件。 - PostToolUse：在工具执行后检查。比如每次编辑完代码自动跑一次 eslint、每次写完测试自动执行指定用例。
我的.claude/settings.json里 hooks 配置长这样：
{ "hooks": { "PreToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "bash .claude/hooks/check_path.sh", "timeout": 10 } ] } ], "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npm run lint:changed", "timeout": 30 } ] } ] } }这段配置的意思是：当 AI 打算编辑或写入文件时，先跑一下check_path.sh，看目标路径是否在允许范围内；等它编辑完成，再自动跑 lint，如果有问题就直接报错，AI 会看到输出并继续修复。matcher字段用于匹配工具名，支持的取值要看当前版本文档，但Edit|Write这个组合是最常用的。
用 hooks 最直接的好处是把标准变成流程，不再依赖 AI 的“自觉性”。那段时间我特别忙，经常靠 hooks 兜底，比如所有新增文件必须包含版权头、所有改动必须通过 lint，否则整轮对话会被标记为失败。设置好之后，即使我一句话不说，AI 也会在错误发生时自己看到反馈并继续修改，等于多了一双不会眨眼的手。
2.4 Agents 与技能模板
再往里一层是agents和skills。这俩解决的是“角色分工”和“方法论复用”。我的模板里有backend和frontend两个子代理，分别限定职责和可用工具。子代理的好处是避免 AI 在一个会话里角色混乱，比如让它处理 API 时不自觉地开始调样式、改布局。
子代理模板的基本写法是：
你是后端开发代理，专注于服务端逻辑。 职责范围： - 设计 API 接口与数据模型 - 编写数据库迁移与单元测试 - 优化查询性能 禁止事项： - 不要修改 frontend/ 下的任何文件 - 不要安装前端依赖 可用工具：读取文件、编辑文件、执行测试、运行数据库命令。skills则更像是一份“操作手册”，描述某个特定任务的标准做法。以我整理的refactor技能为例，SKILL.md 里写清了重构流程：先梳理依赖关系、再列行为清单、然后小步迁移、最后跑全量测试。AI 在相关场景下读到这些内容，输出质量会比临时发挥稳定得多。
这里有个容易忽略的点：子代理的提示词不要太长。它是被主代理按需调用的，每次调用都会占用上下文，把提示词压到 20 行以内，只写职责边界、输入输出约定和禁止事项，具体细节让主代理在任务中子代理时再传递。
3. 实操：从零搭建并落地一套模板
3.1 第一步：初始化目录
先把骨架建好。我习惯在个人工作区建一个独立仓库来保存模板，既不污染正式项目，也方便后面用脚本批量复制。初始化命令很直接：
mkdir -p claude-code-templates/.claude/{commands,agents,skills,hooks} mkdir -p claude-code-templates/templates/backend touch claude-code-templates/CLAUDE.md touch claude-code-templates/.claude/settings.json这一步没什么技术含量，但目录命名要提前想好。commands、agents、skills、hooks都是 Claude Code 的约定目录，不能随意改名；templates是我自己加的，用来放新项目脚手架。如果你还没装 Claude Code，需要先去官网装好，再确认命令行里能正常唤起。
初始化完成后，我建议先做一次“空跑”：在一个临时目录里启动会话，测试CLAUDE.md是否被加载、.claude/settings.json有没有报错。空跑的目的不是验证功能，而是确认没有被其他全局配置干扰。
3.2 第二步：编写主 CLAUDE.md
我写主CLAUDE.md的顺序是“先抄后删”：先把自己平时在对话里反复强调的话全部列出来，再逐条问自己“这条对大多数项目都成立吗？”。成立的留下，只对单一项目成立的移出主模板，放到具体项目的CLAUDE.md里。
第一版可以短一点，我推荐这样起步：
# 通用协作规则 - 动手改代码前，先读取相关文件，说明你的修改计划和影响范围 - 所有命令输出中若出现报错，先分析错误再给出修复，不要直接忽略 - 不要批量修改文件后一次性交付，分批提交并保持每个步骤可回滚 # 输出规范 - 代码块必须标注语言 - 重要结论放在回答最前面，细节放在后面 - 涉及删除、重命名、覆盖文件的操作，必须先征得确认这里有个很关键的误区：CLAUDE.md不是给 AI 背的“规章制度”，而是帮它做判断的“上下文”。你写“所有接口必须返回统一结构”，比写“要求代码风格良好”有用得多。前者可以被检查，后者无法被执行。
写完以后，我建议用一个小技巧验证效果：启动一个新会话，问一句“根据 CLAUDE.md，你在动代码前需要先做什么？”，如果它能准确回答出“先读取相关文件并说明计划”，说明配置已经被正确加载。这个测试我每次改模板都会跑一遍，极其省心。
3.3 第三步：配置 hooks 并验证生效
hooks 是模板里最容易配置错的部分。我踩过的最大一个坑是：settings.json 写错位置。Claude Code 区分三类设置文件：企业级、用户级、项目级。项目级是.claude/settings.json，放在项目根目录；用户级是~/.claude/settings.json，对所有项目生效。如果发现 hooks 没跑，第一反应就是检查文件位置对不对。
配置完成后，验证流程是这样的：
- 在项目里随便放一个
tmp.txt。 - 让 AI 用
Edit工具修改这个文件。 - 观察终端是否输出 hook 的执行结果。
- 故意触发一条禁止规则（比如让它删除
tmp.txt），看是否被 PreToolUse 拦截。
我自己的 hook 脚本最开始只支持 bash，后来把核心逻辑改成了 Python，因为跨平台处理路径和编码更稳。脚本不需要追求复杂，够用就好。比如check_path.sh可以短到只有几行：
#!/usr/bin/env bash path=$(echo "$CLAUDE_TOOL_INPUT" | grep -o '"file_path":"[^"]*"' | cut -d'"' -f4) if echo "$path" | grep -qE '/(node_modules|dist|build)/'; then echo "错误：禁止修改目录 $path" exit 2 fiCLAUDE_TOOL_INPUT是 Claude Code 传给钩子的环境变量，里面是本次工具调用的 JSON 参数。不同版本的变量名可能略有差异，我这里是按当前版本来写的。如果你用的版本不同，先打印一下变量内容再解析，不要直接照抄。
3.4 第四步：用模板批量生成新项目
当模板仓库稳定下来之后，我把它做成了“一键复制”的形式。新建项目时不再手动初始化，而是执行一个脚本，把templates/backend复制到新目录，并用变量替换生成CLAUDE.md。脚本的核心逻辑很简单：
project_name=$1 mkdir -p "$project_name" cp -r templates/backend/* "$project_name/" sed -i "s/{{PROJECT_NAME}}/$project_name/g" "$project_name/CLAUDE.md" cd "$project_name" || exit{{PROJECT_NAME}}这种占位符可以用sed直接替换，也可以写复杂一点，用 Python 脚本读取 JSON 配置批量替换多个变量。我的模板里还加了一个Makefile，把“初始化、安装依赖、启动 AI 会话”串成一条命令，跑完make init接着claude就能直接进入工作状态。
这个环节最大的收益是团队标准化。当整个团队都用同一套模板起步，AI 的产出风格会收敛很多。代码提交信息的格式、接口返回结构的约定、测试覆盖率的要求，都不需要每次沟通。新人来了，照着 README 跑一条命令，就能获得和老手一致的 AI 工作环境。
4. 常见问题与排查技巧实录
4.1 模板没生效：先查优先级，再查路径
我见过最多的问题就是“模板没生效”。排查顺序很重要，我一般按这个表格来：
| 症状 | 优先检查项 | 说明 |
|---|---|---|
| CLAUDE.md 内容没有反应 | 文件位置 | 必须在项目根目录，或在~/.claude/下 |
| 自定义命令找不到 | 命令目录 | .claude/commands/下的 md 文件需要带.md后缀 |
| hooks 没有执行 | settings 优先级 | 项目级 vs 用户级，后加载的会合并或覆盖 |
| AI 输出还是老样子 | 上下文是否过旧 | 改完模板后要新开会话，旧会话不会重新加载 |
有一个细节我要强调：修改CLAUDE.md后，现有会话不会热加载。很多人辛辛苦苦改完，发现 AI 还是按旧规则来，以为配置错了，其实只是没开新会话。另外，如果你用claude --continue继续旧对话，也一样不会加载最新模板。
如果你确认路径没错，但还是不生效，我的建议是直接在项目根目录问 AI：“你记得当前项目有哪些编码约定？”它会复述从 CLAUDE.md 读到的内容。如果它答不上来，说明文件没有被读入上下文；如果它答的内容过时，说明加载了缓存或错误路径。
4.2 AI 不按模板输出：原因通常在提示词的“密度”
模板里写了规范，但 AI 有时还是我行我素。这时先别急着怪模型，绝大多数原因是提示词太“虚”。你写“请保证代码质量”，它不知道怎么才算达标；你写“函数复杂度超过 10 需要拆分，并加注释说明拆分原因”，它就知道这是个硬指标。
我的对策是给每条规则加“可验证动作”。比如不用“不要破坏现有功能”，而是“修改后运行pytest tests/test_existing.py -q，并把测试结果贴到回复里”；不用“注意错误处理”，而是“每个可能抛异常的外部调用，必须写明捕获什么、抛出什么”。当规则能被执行和验证，AI 遵守的概率会大幅提高。
还有一招是把关键规则做成“任务启动检查清单”，让 AI 在执行任何任务的开始阶段就逐项确认。比如模板里写：
开始任务前，请先回复： - [ ] 明确需求 - [ ] 确认涉及的文件 - [ ] 当前测试基线是否通过因为 Claude Code 的对话是流式的，它在第一步列出这个清单时已经确立了工作节奏，后面不容易跑偏。这个技巧我用了很久，比单纯在后面补规则有效得多。
4.3 团队协作：模板冲突与同步
模板一旦变成团队共享资源，就会遇到两个问题：一是有人改了模板导致大家行为不一致，二是各项目积累了特有的 CLAUDE.md，无法反向回收到主模板。
我的处理方式是这样的：模板仓库要求所有改动走 PR，并且每个 PR 必须附上“改善说明”，说清楚为什么加这条规则、它会被哪些项目影响。主模板的变更会定期同步到各个项目，使用claude-code-templates配合脚本，重跑一次setup把主模板复制过去。
另外，项目特有的规则不要往主模板塞。比如“支付模块禁止改动”这类只在一个项目里成立的约束，写在那个项目的 CLAUDE.md 里就够了。主模板只放普适性规则。一开始我总想把所有细节都集中管理，结果来回同步反而制造了更多冲突，后来才明白“集中”和“隔离”要平衡。
4.4 让我最意外的一个坑：shell 变量注入
排查 hooks 问题时，我遇到过一个很有意思的现象：配置里的$ARGUMENTS在自定义命令里能正常用，但在 hooks 命令里会被 shell 提前展开，导致参数变成空字符串。当时的 hook 脚本里写了类似bash .claude/hooks/run.sh $ARGUMENTS，结果执行时$ARGUMENTS被本地 shell 解析成空值，什么都传不进去。
这个问题的本质是混淆了“Claude Code 的模板变量”和“shell 环境变量”。自定义命令里的$ARGUMENTS是 Claude Code 在注入提示词时替换的；hooks 的command字段是交给 shell 执行的，所以要引用环境变量时得写成"$CLAUDE_TOOL_INPUT"，要注意引号和转义。
排查这种问题的方法也简单：在脚本里第一行加env > /tmp/hook_env.log，看看实际传入了哪些变量。我后来把所有 hooks 脚本都统一用 Python 解析 JSON 入参，不再依赖 shell 传递参数，彻底绕开了这类转义问题。
根据我维护这套claude-code-templates的体会，模板最大的价值不是“让 AI 一次就做对”，而是“让 AI 每次都在同一套标准下工作”。你可以从一个小命令开始，把一个反复出现的需求固化成模板，再逐步加入 CLAUDE.md、hooks、agents。等这套东西跑起来之后，你会发现自己不再需要事无巨细地盯对话，因为规则已经嵌在流程里了。
