把 Claude Code 用出生产力的团队大多不是靠即时对话而是靠一套沉淀好的模板。我在自己项目里连续折腾了几周后有一个很明显的体感claude-code-templates 这个方向的本质是把你在终端里反复跟模型讲的业务背景、编码偏好、工作流程固化成一类可以被复用、被升级、被团队共享的资源文件。这篇文章我会把这些实践完整摊开从模板体系怎么分层、CLAUDE.md 里到底该写什么到自定义命令和钩子怎么串联再给一套可以直接抄走的模板合集最后讲讲最常踩的几个坑。这个方向适合谁如果你只是偶尔拿 Claude Code 改个脚本可能用不太上但只要你的团队已经把 Claude Code 纳入日常开发循环——写提交信息、做 Code Review、生成测试、跑项目初始化——那模板化就是一条绕不开的路。跟带新人一样如果每次都要从头交代项目背景AI 给的答案永远泛泛而谈把背景和方法固化下来之后它的输出质量会出现肉眼可见的跃升。1. 先想清楚Claude Code 模板到底解决什么问题1.1 为什么要给 Claude Code 做模板先说一个很普遍的现象。很多人第一次用 Claude Code觉得它“很聪明”但用着用着就会发现它在同一个项目里反复犯同样的错误不知道项目的构建命令、不遵守代码风格、Review 的时候抓不住重点。问题不在模型能力而在于它每次启动都是一张白纸你上一次交代的所有上下文都会在会话结束或上下文压缩之后丢失。模板化解决的就是这个“重新解释”的成本。你把自己的项目知识、团队规范、操作流程写进模板文件Claude Code 启动时会自动读取相当于给模型发了一本“入职手册”。之后每次对话它都默认知道这些背景不用你再啰嗦。这跟带新人是一个道理你给新人讲一百遍注意事项不如给他一份写得好的 SOP。我自己的体会是模板化的收益不是线性的而是越到后期越明显。刚开始搭建模板要花几个小时可一旦搭好后续每个任务都能省下大量的“前摇时间”——它不会再问“你们的测试命令是什么”而是直接按照模板里写的命令去执行。1.2 模板体系的四个层级把 claude-code-templates 拆开看它不是一个单一文件而是一个分层体系。我通常会把它分成四个层级层级存放位置作用全局提示词模板~/.claude/CLAUDE.md对所有项目生效的个人偏好、通用工作流项目提示词模板.claude/CLAUDE.md当前项目的架构说明、命令、规范自定义命令模板.claude/commands/*.md把高频操作固化为 slash command钩子模板.claude/hooks/*在工具调用前后自动执行校验或拦截这四个层级各司其职。全局模板管住“你这个人怎么工作”项目模板管住“这个项目怎么回事”命令模板管住“某个具体任务怎么做”钩子模板管住“哪些事绝对不能做”。真正成熟的团队这四个文件是同时存在的而且会一起放进 Git 仓库里管理。很多人在第一层和第二层之间容易犯迷糊。我的建议是凡是跨项目通用的一律放全局凡是跟当前仓库强相关的一律放项目。比如“提交信息要遵循 Conventional Commits”这种偏好可以放全局而“本项目后端是 FastAPI启动命令是 make dev”这种信息必须放项目否则换个项目就全是噪音。1.3 模板变量与上下文注入机制Claude Code 的模板不是死文字它也支持变量注入。在自定义命令里$ARGUMENTS指代用户输入的全部参数$1、$2指代按空格分隔的位置参数$CLAUDE_PROJECT_DIR是当前项目根目录。这个机制让你能写出动态模板而不是每次都要改文件。我举个例子你写一个/commit命令模板正文里写“请根据以下 diff 生成提交信息$ARGUMENTS”用户执行/commit时输入的就是 diff 内容或文件路径。这样同一个模板可以服务无数次不同的提交。除了变量注入Claude Code 还会自动加载项目里的关键文件作为上下文比如CLAUDE.md、AGENTS.md以及你在对话里引用的文件。理解这套机制后你在设计模板时就会刻意控制“模板自身的长度”和“会触发自动读取的文件范围”避免把上下文窗口撑爆。2. 核心模板详解CLAUDE.md、自定义命令与钩子2.1 CLAUDE.md把项目说明书变成可执行配置CLAUDE.md 是整套模板体系里最核心的文件也是投入产出比最高的一份配置。它的本质是给模型看的项目说明书但它不是文档而是“可执行偏好”。写成什么样直接决定模型在这个项目里的行为表现。我一般建议 CLAUDE.md 包含五个区块项目概况、常用命令、架构索引、编码规范、工作流说明。其中“常用命令”和“架构索引”最容易被忽略但恰恰是提升效率的关键。模型知道怎么跑测试、怎么起服务、代码放在哪些目录之后你在对话里就不用反复给它贴路径。# 项目名称 ## 项目概况 这是一个基于 FastAPI React 的工单系统核心业务域是工单流转与权限管理。 ## 常用命令 - 启动后端开发服务make dev - 运行全部测试make test - 单测某个文件pytest tests/test_ticket.py -x - 数据库迁移alembic upgrade head ## 架构索引 - 后端入口backend/app/main.py - 路由层backend/app/routers/ - 业务逻辑backend/app/services/ - 前端页面frontend/src/pages/ ## 编码规范 - Python 使用 Black 默认格式行宽 88 - 错误处理使用自定义异常禁止裸抛 Exception - 所有对外接口必须写 OpenAPI 响应模型你可能会问写这么详细模型每次都读会不会浪费 Token我的实测是一份控制在几百行内的 CLAUDE.md对上下文窗口的影响微乎其微但它换来的是每次对话质量的全面提升。真正浪费 Token 的不是读这份文件而是模型因为不知道命令去瞎猜、反复试错。还有一个实操技巧不要试图让 CLAUDE.md 覆盖所有边界。模型是概率推理你给它写太多互相冲突的规则它反而不知道该听谁的。我的做法是只写“高频复用”和“硬性规定”两类每一类控制在十条以内把最关键的约束放在最前面。2.2 自定义命令模板把高频操作固化成 slash commandCLAUDE.md 解决的是“背景知识”自定义命令解决的是“固定动作”。当你在项目里经常执行同一类任务——提炼提交信息、做代码审查、生成接口文档、初始化模块——就应该把这些任务写成 slash command放在.claude/commands/目录下每个.md文件对应一个命令。一个标准命令模板包含两个部分YAML frontmatter 和正文。frontmatter 里常见字段是description命令说明、argument-hint参数提示、allowed-tools允许使用的工具白名单。正文就是你希望模型执行的任务描述可以使用上面说的$ARGUMENTS等变量。--- description: 根据暂存区 diff 生成 Conventional Commit 提交信息 argument-hint: 可选补充额外的提交说明 --- 请执行以下任务 1. 运行 git diff --staged 获取暂存区改动 2. 分析改动类型判断是 feat/fix/refactor/docs/test/chore 中的哪一类 3. 结合 $ARGUMENTS 中的补充说明生成提交信息 4. 输出格式为 类型(影响范围): 简述 示例 feat(auth): 增加基于 JWT 的刷新令牌机制这个模板设计的关键点是我把“分析改动类型”“输出格式”都写死在模板里模型不会有自由发挥的空间。如果你只写一句“生成提交信息”它输出的格式可能每天都不一样Commitlint 那边就会开始报警。我强烈建议从最常用的三个命令开始/commit、/review、/test。这三个命令覆盖了日常开发里最重复、最容易被敷衍的环节。先把它们跑顺再根据团队的实际痛点扩充其他命令。命令宁缺毋滥一个没人用的死命令比没有更糟。2.3 钩子模板给工具调用装上自动守门如果说命令模板是“主动调用”钩子Hooks就是“被动触发”。Claude Code 在每次工具调用前后会触发一系列事件比如PreToolUse、PostToolUse、UserPromptSubmit。你可以在.claude/hooks/目录下放脚本让它在这些事件发生时自动执行。最典型的应用场景是安全卡点。比如你想禁止模型直接往main分支推送代码就可以写一个PreToolUse钩子检测到 Bash 工具执行git push时检查当前分支如果命中main就拦截掉又比如你想保证代码风格可以在PostToolUse钩子里对 Edit 工具写过的文件自动跑一遍格式化。钩子的写法因语言而异脚本接收 JSON 输入输出 JSON 控制是否放行。下面是一个示意形态的 Bash 片段目的是在git push前检查分支名#!/bin/bash input$(cat) tool_name$(echo $input | jq -r .tool_name) tool_input$(echo $input | jq -r .tool_input // ) if [[ $tool_name Bash $tool_input *git push* ]]; then current_branch$(git rev-parse --abbrev-ref HEAD) if [[ $current_branch main ]]; then echo {permissionDecision: deny, reason: 禁止直接推送 main 分支} exit 0 fi fi echo {permissionDecision: allow}这个示例的完整逻辑要根据你用的语言和官方 Schema 微调但思路是通用的。钩子不是用来做所有校验的它的定位是“守门员”只负责拦截那些一旦发生就代价很高的错误比如误删分支、推送主分支、执行危险命令。常规的代码风格问题用命令模板提醒就够了。3. 实操实录从零搭建一套可复用的模板库3.1 目录结构与全局配置准备理论讲完下面直接进入操作。我建议在任何项目里都按下面的结构组织模板文件。这套结构我自己用了很久符合 Claude Code 的默认加载规则也方便团队 Review。project-root/ ├── .claude/ │ ├── CLAUDE.md # 项目级提示词模板 │ ├── settings.json # 项目级权限与工具配置 │ ├── commands/ # 自定义 slash commands │ │ ├── init.md │ │ ├── commit.md │ │ ├── review.md │ │ └── feature.md │ └── hooks/ # 钩子脚本 │ ├── PreToolUse/ │ │ └── protect-main.sh │ └── PostToolUse/ │ └── auto-format.sh同时你在~/.claude/CLAUDE.md里可以放全局配置比如“所有代码修改必须同时更新对应测试”“提交信息遵循 Conventional Commits”这类跨项目通用的规则。全局配置的好处是你的个人偏好不用每个项目重写一遍项目配置只需要关注跟当前仓库强相关的内容。初始化这些配置时有一点容易忽略.claude/目录应该纳入 Git 版本管理而不是写进.gitignore。很多人习惯把所有带点的目录都忽略掉结果模板改了也没法 Review、没法回滚。模板是会演化的它跟代码一样需要走变更流程。3.2 项目初始化模板/init先写一个/init命令目的是当你在一个新仓库里启动 Claude Code 时让它自动梳理项目结构并生成一份 CLAUDE.md。这个命令的价值在于很多项目文档陈旧手动写 CLAUDE.md 容易失真用 AI 自己读代码生成的版本反而更贴近现状。--- description: 扫描项目结构生成或更新 CLAUDE.md --- 请完成以下项目初始化工作 1. 使用工具读取当前目录下的一级子目录和关键配置文件 2. 识别项目的技术栈、构建工具、测试框架 3. 查找包管理配置文件提取可用的 npm/pip/make 等脚本命令 4. 阅读 README 中的快速开始部分交叉验证命令 5. 将结论写入 CLAUDE.md结构参考 - 项目概况不超过五行 - 常用命令列出启动/测试/构建/迁移 - 架构索引标注核心代码目录位置 - 编码规范从 lint 配置反推不要臆测 6. 如果发现无法确定的信息明确标注 TODO不要编造这个模板里最关键的约束是第 5 条和第 6 条。如果不加这两句模型很可能会凭经验脑补一堆实际不存在的配置比如它看到manage.py就默认 Django但你的项目可能只是借用了文件命名。我给它加一个“TODO 标注”的出口它没把握的地方就不敢乱写了。实际执行时你会发现这个命令不仅生成了 CLAUDE.md还会顺带暴露项目里很多坑——比如测试命令跑了五分钟没反应、lint 配置跟代码风格自相矛盾。这些信息放进 CLAUDE.md 之后团队成员用 Claude Code 时就不会再踩同样的坑。3.3 提交信息模板/commit接下来是/commit这是我用频率最高的模板。它要干的事很简单从暂存区读 diff生成符合规范的提交信息。但它有一点很讲究不能只读全量 diff否则改动一大Token 全费在提交信息上其他任务就没得做了。--- description: 根据暂存区 diff 生成提交信息 argument-hint: 输入 \--wip\ 标记草稿提交输入其他内容作为补充说明 --- 请生成 git 提交信息 1. 运行 \git diff --cached --stat\ 查看改动的文件概览 2. 运行 \git diff --cached -- 文件路径\ 查看具体 diff 3. 如果 $ARGUMENTS 包含 \--wip\忽略规范检查输出 wip: 临时提交 4. 分析改动类型匹配 Conventional Commits 的类型前缀 - feat: 新功能 - fix: 修复缺陷 - refactor: 重构不影响功能 - docs: 文档变更 - test: 测试相关 - chore: 构建工具、依赖等杂项 5. 生成一行简要标题 三行内的正文说明 6. 输出前检查标题不要超过 72 字符正文按 72 字符换行这里我特意把“查看统计信息”和“查看具体 diff”拆成两步而不是让模型直接一把梭读全量 diff。当项目改动超过几十个文件时全量读一次费的 Token 相当可观而且很多信息根本用不上。先看统计再针对性地看关键文件速度和成本都能省很多。你可能会问为什么不直接用 Claude Code 内置的自动提交功能我的实测是内置功能生成的提交信息偏保守格式比较松散。而我们的团队有 Commitlint 强制校验格式不对 CI 直接红。用模板把格式约束写死一次就过省了跟模型反复拉扯的时间。3.4 代码评审模板/review代码评审模板是另一个值得重点投入的方向。它跟提交信息模板相反提交信息追求“短而准”Review 追求“全面但有侧重”。如果让模型自由发挥它经常会输出一堆正确的废话——说“这里可以优化一下”但说不清为什么要优化、怎么优化。--- description: 对指定范围或全部未提交改动进行代码审查 argument-hint: 可选指定审查范围如 \src/auth\ 或 \main...feature-x\ --- 请执行代码审查审查对象$ARGUMENTS 1. 获取改动范围如果提供了路径参数只审查该路径否则审查所有未提交改动 2. 按以下优先级审查 - 正确性是否存在明显的逻辑错误、空指针、资源未释放 - 安全性是否存在越权访问、注入、敏感信息硬编码 - 可维护性函数是否过长、命名是否达意、是否有重复代码 - 一致性是否遵循 CLAUDE.md 中的编码规范 3. 每条反馈必须包含问题位置、为什么是问题、建议的修改方向 4. 禁止输出空洞评论比如“代码清晰易懂”“建议优化” 5. 最后输出汇总优先级 P0必须改/ P1应该改/ P2可以改这个模板的核心价值在第 3 条和第 4 条。我见过太多 AI Review 输出“函数命名不够清晰建议改善命名”——这种评论放到团队里就是噪音。把“每条反馈必须包含问题位置和原因”写进模板之后输出的质量立刻提升一个档次每条评论都能直接作为提交意见使用。还有一个技巧Review 模板我通常搭配git diff范围参数使用。Code Review 的时候我常常只想看某个功能分支相对主分支的差异而不是所有未提交改动。$ARGUMENTS里传入分支名范围之后模型就会用git diff main...feature-x来拿 diff而不是默认只看工作区这样实用性更强。3.5 功能开发模板/feature最后是一个偏重流程的模板。团队成员用 Claude Code 时长长会有一个问题让它开发一个功能它动不动就把所有文件全改了或者直接开始写代码而不写测试。/feature这个模板就是把“功能开发”这件模糊的事情拆成带检查点的流程。--- description: 按标准流程开发一个新功能 argument-hint: 功能描述如 \增加用户头像上传接口\ --- 请按以下流程开发功能$ARGUMENTS 阶段一需求澄清 - 用 5 个以内的提问确认关键决策点 - 如果有歧义列出你的默认假设 阶段二方案设计 - 列出涉及的文件路径和改动范围 - 说明数据流和接口签名 - 等待用户确认后再进入编码阶段 阶段三编码实现 - 遵循 CLAUDE.md 中的编码规范 - 每个文件编写后运行对应的静态检查 阶段四测试补充 - 为新增代码编写单元测试覆盖正常和异常路径 - 运行相关测试直到全部通过 阶段五变更总结 - 输出改动文件清单 - 列出测试命令和建议的提交信息 在每个阶段结束时停下等待用户确认后再进入下一阶段。最后那句“在每个阶段结束时停下”是整个模板的灵魂。没有这句模型大概率会一口气冲到底等你发现方案跑偏时已经浪费了大量时间。让它在每个关卡停下来等你确认看起来慢实际是最快的方式——方向错了越快到终点越糟糕。我自己的习惯是/feature模板配合settings.json里的权限配置一起用。编码实现阶段不允许模型自动执行数据库迁移这类高影响操作把Bash(migrate*)之类模式加进 deny 列表。这样即使模型方案设计里出现迁移动作也会被权限层拦下来等你手动确认。4. 常见问题与排查技巧实录4.1 模板不生效问题出在哪我用模板踩过的第一个坑就是“为什么我改了 CLAUDE.md模型完全没有反应”。排查一圈后确认CLAUDE.md 的变更不会热更新需要重启会话才生效。如果你在对话中途改了文件当前会话里模型读到的仍然是旧内容这是最容易让人产生“模板没用”错觉的原因。第二个坑是文件位置放错。全局模板放在~/.claude/CLAUDE.md或~/.claude/里项目模板放在项目根目录的.claude/CLAUDE.md同一份 CLAUDE.md 如果既出现在用户目录又出现在项目目录项目目录的优先级更高。自定义命令只能放在commands/目录下文件名就是命令名不能有大小写之外的特殊字符否则 slash 列表里不显示。现象可能原因排查方式模板内容完全没有生效会话未重启输入/clear或重启 Claude Code命令不在 slash 列表里文件名非法或目录不对检查.claude/commands/结构命令能显示但执行报错frontmatter 拼写错误检查 YAML 字段名是否多了空格CLAUDE.md 优先级不对多份文件内容冲突确认项目文件优先于全局文件还有一类情况特别隐蔽.claude/目录被.gitignore忽略了导致你在电脑 A 上改的模板推到远端后电脑 B 上根本不存在。我们的解决方式是把.claude/强制加入 Git 跟踪并在团队文档里写明“模板是项目资产不是个人配置”。4.2 上下文被模板吃光怎么办模板虽然好但模板本身也会占上下文窗口。如果你的 CLAUDE.md 写成了两三千行的项目百科全书那一次会话刚开始模型的世界里就全是模板内容真正要处理的代码信息反而被挤掉了。这是很典型的“配置过度”问题。我的做法是给 CLAUDE.md 定一个红线常规项目控制在 200 行以内超过 300 行就必须开始拆分。拆分的思路不是删内容而是把细节外置。比如把“数据库所有表和字段的说明”单独放到docs/db-schema.md在 CLAUDE.md 里只写一句“涉及数据库表结构时先读docs/db-schema.md再作答”。这样模型需要的时候才会去读不会一开局就把所有细节全部装进来。还有一个技巧是用.claude/settings.json里的ignorePatterns控制自动上下文加载。某些大文件、导出目录、日志文件根本不该被模型自动扫描加了 ignore 之后模型在需要时仍然可以显式读取但不会被动地把整个目录都灌进上下文。实测下来这一个操作能让长会话的可用上下文多出不少。4.3 权限与安全边界怎么守模板越强大越要防住它“自作主张”。我自己就遇到过模型按照 CLAUDE.md 里的测试命令执行了一段耗时很长的集成测试虽然命令是对的但执行时机不对浪费了很多时间。而真正危险的是那些高影响操作删除分支、推送远端、批量改文件、执行数据库迁移。在模板里写“注意安全”之类的提示词基本没用模型该执行还是会执行。真正可靠的防线是settings.json里的权限配置。我一般把Bash(rm -rf *)、Bash(git push origin main)、Bash(migrate*)这类会改变全局状态的操作加入 deny 列表或者在 allow 列表里只放白名单命令。权限层是硬拦截模型无法绕过这比任何提示词都可靠。钩子也是安全防线的一部分。PreToolUse钩子的定位就是“不可绕过的事前检查”。我见过一个团队用钩子拦截所有对.env文件的批量修改还有团队用钩子阻止模型在非工作时间执行耗时任务。钩子不要写太多每多一个钩子就多一份维护成本和误伤风险我把它的位置定义为“只拦截那些一辈子只能错一次的操作”。5. 模板库的版本管理与团队共享5.1 把模板当代码一样管理模板不是一次写完之后就躺在那儿的东西。项目在变依赖在变团队规范也在变模板必须跟着演进。我见过最典型的翻车现场是团队 CLAUDE.md 里写着“本项目使用 Django 2.2”实际项目早就升级到 Django 4.2模型按照旧规范给出的建议全是错的。我们现在的做法是把 claude-code-templates 作为一个独立的 Git 仓库管理版本号用 SemVer。CLAUDE.md 的大结构变更算 minor 版本新增命令算 minor修复一个措辞算 patch。每次模板变更都走 MR 流程Review 的人不光看文字还要看“模型在这个模板驱动下实际产出的对话记录”验证它是不是真的有效。模板仓库还有一个隐藏的价值它就是团队的“开发文化说明书”。新人加入时与其给他发一堆 PPT 讲团队规范不如让他从头到尾读一遍模板仓库。他在读模板的过程中就理解了项目怎么启动、代码怎么组织、提交怎么约束、安全红线在哪——这比任何入职培训都直观。5.2 团队规范的分层落地团队共享模板最大的挑战是“统一与灵活”的平衡。如果所有规范都写进全局模板那每个项目都会被迫接受一套并不适用的约束如果什么都写进项目模板那每个项目都要重复造轮子。我常用的分层规则是全局模板只放“价值观层”项目模板放“实现层”。所谓价值观层是那些跨项目都成立的原则比如“所有修改必须同步更新测试”“禁止提交敏感信息”“先设计再编码”。实现层是那些跟具体技术栈强相关的内容比如“这个项目用 pnpm不用 npm”“这个项目的前端在app/目录不在src/目录”。前者一层就够了后者每个项目各有各的写法。团队里推行模板化的时候阻力往往不在工具本身而在习惯。有人觉得“让模型自己发挥不是更灵活吗”但实际做下来大部分人的“灵活”其实是“随机”。我自己的体会是模板不是用来限制模型创造力的而是用来兜底的。模型在框架内自由发挥创造力框架本身必须稳定可靠。把这句话讲清楚团队协作推进就会顺畅很多。最后分享一个我从踩坑中得到的经验给模板写“测试”。听起来有点夸张但方法是有的——准备一个假项目在里面跑一遍/init、/commit、/review把输出结果人工检查一遍看它有没有遵循模板里的规则然后把检查结论写进模板变更说明里。每次改模板就在假项目里重跑一遍这样模板质量不会随时间的推移悄悄腐烂。我现在的模板库能一直保持稳定可用靠的并不是一开始写得多完美而是这套持续打磨的循环。