如果你也跟我一样每天要在终端里打开 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。等这套东西跑起来之后你会发现自己不再需要事无巨细地盯对话因为规则已经嵌在流程里了。