Claude Code 模板库：用 CLAUDE.md、斜杠命令与 hooks 固化 AI 协作规则

用过 Claude Code 的朋友应该都有这种体会单次会话里它能干得漂亮但换一个项目、隔几天再继续它又像失忆一样把之前约定好的代码风格、目录习惯、口头禅式的约束全忘干净了。我也曾被这个问题折磨过很久直到我把散落在各个项目里的 CLAUDE.md、斜杠命令、校验脚本集中整理成一个模板库也就是今天要聊的 claude-code-templates整个效率才算真正提上来了。这名字听起来像是一个项目模板仓库其实本质上是把 Claude Code 的使用从随用随写变成有一套可以复用的规则包。它解决了几个非常具体的问题新项目初始化时不用从零教 AI 项目背景团队协作时每位成员的 Claude Code 行为保持一致遇到重复的代码审查、测试生成、提交信息整理等耗时操作不用每次重新写一遍提示词直接敲一个斜杠命令就行。如果你是重度用户或者正打算把 Claude Code 引入团队工作流这套东西就是那个把散装经验变成资产的关键一步。1. 先搞清楚Claude Code 模板到底在解决什么问题很多人听到模板两个字第一反应是不就是一个写好的提示词吗。刚开始我也是这么以为的但真正用下来才发现Claude Code 里的模板体系比单纯提示词要复杂得多它更像是一套运行规则贯穿在 AI 的读取、思考、执行、反馈各个环节里。先说最核心的痛点。Claude Code 是上下文感知的但它感知的上下文来自当前会话、当前目录、和智能体能够读到的项目文件。如果你不做任何约束它就只会按照通用偏好和最近对话内容来输出代码风格可能跟你的项目格格不入目录结构也可能被改得乱七八糟。有人觉得那我每次都在对话里强调一遍就好试过就知道这句话只能管住当前会话一旦新开会话或者换个人操作同样的错误一遍遍重演。模板的作用就是把每次都要说的话固化下来。项目根目录的 CLAUDE.md 可以描述这个项目是什么、用哪些技术栈、代码风格怎么统一、有哪些绝对不能碰的目录。全局的 ~/.claude/CLAUDE.md 则用来沉淀你个人的工作习惯比如所有改动必须附测试“提交信息用中文还是英文”“遇到不确定的依赖版本先查官方文档”。这两个文件配合起来Claude Code 在每次启动和读取文件时就会自动把这些规则当作背景知识根本不需要你重复输入。再进一步模板不只是规则文本还包括可执行的命令和动作。比如你经常做数据库迁移那就可以把迁移流程打包成一个自定义斜杠命令你希望每次改动后自动跑一次 lint那就可以在 hooks 里配置一个预执行检查。这些东西单独看都是小工具组合在一起就形成了一套标准的操作流程让 AI 不是好像懂了而是按你的套路出牌。对我个人来说这个项目最大的价值不是省了多少次输入而是把 AI 协作过程中的不确定性压缩了。以前我和团队里其他人同时用 Claude Code 处理同一段代码出来的结果风格差异很大现在大家共享同一套 claude-code-templates至少基础规则是一致的讨论问题的时候沟通成本降低了一大截。2. 拆解四类模板别只盯着 CLAUDE.md一个常见的误区是提到 Claude Code 模板就以为只有 CLAUDE.md。实际上一个成熟好用的模板库通常由四类内容组成各有各的使用场景。我把它们拆开讲方便你对照自己项目的实际需要。2.1 CLAUDE.md项目的操作手册CLAUDE.md 是 Claude Code 最传统也最基础的配置载体本质上是给 AI 看的项目文档。官方会默认读取当前目录下的 CLAUDE.md以及用户目录下的全局配置文件里的内容会随着会话内容一起被当作上下文参考。写这个文件的关键不是把项目文档抄一遍而是用极简的语言告诉 AI 三件事这个项目要解决什么问题、约定用什么方式解决、哪些事情绝对不能做。比如一个后端 API 项目可以写# 项目简介 这是一个面向外部客户的身份认证服务提供注册、登录、令牌刷新等接口。 # 技术栈 - Python 3.11 FastAPI - PostgreSQL 15 - Redis 7仅用于缓存 # 代码约定 - 所有接口返回统一结构{code: 0, message: ok, data: ...} - 数据库操作必须走 SQLAlchemy 的 Session 上下文管理器 - 日志统一使用 structlog禁止 print 输出 - 测试文件放在 tests/ 目录命名 test_*.py # 绝对禁止 - 不要修改 migrations/versions/ 下的历史迁移文件 - 不要绕过当前用户的权限校验逻辑 - 不要新增第三方依赖除非先和负责人沟通这些内容越具体AI 的行为偏差就越小。特别要留意绝对禁止这个分区我见过太多项目只写正向规范没有负向约束结果 AI 一碰到模糊判断就自作主张。2.2 斜杠命令把常用操作变成菜单CLAUDE.md 是用来定义 AI 的世界观的斜杠命令则是用来定义 AI 的交互方式的。Claude Code 支持在项目目录的 .claude/commands/ 下放置 Markdown 文件文件名就是斜杠命令的名字。例如写一个review命令团队里所有人输入/review就能触发一次统一的代码审查流程。命令文件里可以包含提示词、占位符参数和行为说明。最简单的例子--- description: 对当前改动进行代码审查重点检查安全与逻辑边界 argument_hint: 可选传入需要额外关注的模块路径 --- 请对本次 git diff 的改动做代码审查重点检查 1. 是否存在 SQL 注入或未处理的用户输入 2. 交易、锁、并发场景是否有竞态风险 3. 新增代码是否符合 CLAUDE.md 中约定的提交规范 4. 给出一个最终结论pass / fail如果是 fail列出必须修复的点 额外关注 {argument}这个机制的妙处在于AI 不再需要你临场组织语言它只要读取命令文件里的指令就知道该往哪个方向思考。我平时会把高频动作比如生成迁移脚本、跑回归测试、补 changelog、格式化代码全部做成斜杠命令。刚开始写命令会慢一些但积累到十几个以后日常操作的效率是肉眼可见的提升。2.3 hooks在关键节点自动兜底如果斜杠命令是人主动发起动作那 hooks 就是AI 自动触发的护栏。Claude Code 的 hooks 系统允许你定义在某些事件发生时执行特定脚本比如在工具调用前检查路径在会话结束前自动做一轮校验甚至可以在 AI 准备执行危险命令时中止它。最常见的用法是跟静态检查工具结合。比如在 .claude/settings.json 里挂一个 hook当 AI 要执行git commit的时候先自动跑一遍测试和 lint只有通过才放行{ hooks: { PreToolUse: [ { matcher: [git-commit], hooks: [ { type: command, command: ./scripts/check-before-commit.sh } ] } ] } }这个脚本可以自己写也可以用现成的工具核心作用是给 AI 的行动力套上一道缰绳。我见过很多人抱怨AI 跑起来不靠谱动不动就把测试搞挂了其实很多问题不是 AI 干活不靠谱是没人给它设置边界。hooks 就是那个边界。2.4 技能包与子智能体让模板具备分工能力这部分属于 Claude Code 里更进阶的功能。如果你把模板库做成一个插件可以包含 Agent Skills也就是 SKILL.md 文件描述某个技能的触发条件、使用步骤和示例。这跟斜杠命令的区别在于技能是隐式存在的AI 会在任务符合条件时自动决定是否调用。一个简单例子你经常需要处理日志分析任务就可以写一个log-analysis技能定义它适用的场景、应该读取哪些目录、输出什么格式。当 AI 发现当前任务涉及日志排查时它会把这份技能加载进来按照约定的路子执行而不是临场瞎猜。这种带技能分工的模板库团队用起来特别像给 AI 定了岗位职责——有的技能负责前端调优有的技能负责数据库诊断彼此之间由主模型调度。模板库因此不再是一段文本而是一个微型智能体操作系统。3. 手把手搭一套可用模板从场景到落地前面讲了不少概念下面进入实操环节。假想你现在有一个新的 Python FastAPI 项目想要让 Claude Code 从第一天起就按照你的习惯工作我会按照下面的步骤一步步把一个初始模板库建起来。3.1 先定义你实际的工作流而不是凭想象堆配置很多人在搭建模板时犯的第一个错误是在没想清楚工作流的情况下就开始写规则。结果写出来的模板里堆了几十条规定AI 是记住了所有规则但规则和规则之间互相冲突遇到真实任务反而不知道听谁的。正确做法是先列一个清单你在项目里最常做的操作是什么哪些操作是每次都必须做而且流程固定的哪些是坑最容易被反复踩的比如我作为后端开发我的清单是新功能开发建模型 - 写迁移 - 写服务层 - 写接口 - 补测试代码审查看 diff - 自查安全隐患 - 检查命名 - 给结论提交代码跑测试 - 跑 lint - 生成提交信息排查问题看日志 - 定位原因 - 写修复 - 回归这四个流程就是模板的核心骨架。我要做的不是写一个万能文档而是分别给这四个流程准备对应的斜杠命令、hook 和说明文档。这样模板库一开始就很轻每个文件都有明确的使命。3.2 写一个不浮夸的 CLAUDE.md 骨架新建项目后第一件事是在根目录放一个 CLAUDE.md。我建议不要一上来就写一堆细节先写骨架后续在过程中逐步补充。我的最低限度模板是这么几段# 项目角色 这是一个基于 FastAPI 的用户认证服务面向 C 端安全优先级最高。 # 关键约束 - Python 版本固定为 3.11依赖用 uv 管理 - 所有数据库改动必须生成迁移文件不允许手工改表 - 除了 tests/ 目录任何测试输出不允许写到项目根目录 - 新接口默认返回统一响应结构错误码必须登记到 errors.md # 常用命令 - 启动uv run uvicorn app.main:app --reload - 测试uv run pytest - 迁移uv run alembic revision --autogenerate # 需要避免的操作 - 不要删除或修改 .github/ 下的 CI 配置除非确认不再需要 - 不要在业务代码里直接使用 Redis 的 flushall - 不要使用裸 SQL 拼接用户输入这个骨架已经能定住大方向。注意我没写任何你是一个优秀工程师之类的空话也没有把整个公司技术文档搬进去。AI 需要的是边界清晰、可执行的信息不是一篇充满美德但毫无约束的散文。3.3 把高频操作固化成斜杠命令骨架有了我开始写第一波斜杠命令。在项目根目录创建.claude/commands文件夹然后按功能命名。比如我要做一个新功能投产前的一站式检查命令文件名叫ship-ready.md--- description: 新功能交付前检查运行测试、lint、迁移一致性检查 argument_hint: 可选传入需要特别关注的模块名 --- 请按以下步骤检查当前新功能是否达到交付标准 1. 运行 uv run pytest如果失败直接列出失败的用例和原因 2. 运行 uv run ruff check .有报错就指出文件位置和修复建议 3. 检查最近新增的模型是否存在未生成 Alembic 迁移文件的情况 4. 审查 git diff确认没有调试代码、临时文件被提交 5. 最后给出一份 Summary包含通过/不通过、遗留风险和修复建议 额外关注{argument}然后我再写一个fix-lint命令专门负责自动修 lint 问题。new-migration命令负责生成数据库迁移文件。这从一开始就避免了同一件事每次换个说法让 AI 执行的尴尬。这里有个经验分享命令文件的 description 字段要写得具体因为 Claude Code 在模糊判断时会根据 description 来选择是否启用某个命令。描述越准确触发率越高。不要把 description 写成抽象的代码检查要写成对未提交的 diff 做安全与风格检查并输出结论。3.4 用 hooks 做代码质量拦截写完成本后我会同步配置 hooks。还是那个逻辑你不能指望每个人的自觉性机器自动拦截才靠谱。在.claude/settings.json里我给提交动作加了一道预检{ hooks: { PreToolUse: [ { matcher: [GitCommitCreated], hooks: [ { type: command, command: cd $CLAUDE_PROJECT_DIR uv run pytest -x -q --tbshort } ] } ] } }这个 hook 的意思是当 AI 准备创建提交时先跑一遍测试测试不通过提交动作就不应该继续。实际效果是AI 通常会在提交前自己先把测试跑一遍因为它知道跑不过就会被拦下来。我见过不少团队花钱买各种 AI 协作工具却忽略了这种最朴素的质量门禁。写 hooks 的时候有几点要注意一是matcher的大小写和事件名称不同版本可能略有差异最好先查一下当前版本的官方示例二是脚本本身要考虑执行时间如果 hook 里跑一个五分钟的 E2E 测试AI 的整个会话体验都会变得很拖沓。我的建议是 hook 只拦截那些几秒钟内能跑完且必须过的检查重型验证放到专用命令里需要时手动触发。3.5 给模板做版本管理和目录结构模板文件跟普通项目的代码文件一样需要版本管理。我在项目里会单独建一个templates/目录把 CLAUDE.md、commands、hooks 的种子文件都放进去再通过脚本复制到各项目里。这样既能给每个项目保留自定义空间又能方便模板本身的迭代。目录结构大概长这样claude-code-templates/ ├── common/ │ ├── CLAUDE.md # 通用项目骨架 │ └── commands/ │ ├── ship-ready.md │ ├── fix-lint.md │ └── new-migration.md ├── python/ │ └── CLAUDE.md # Python 项目专属规则 ├── node/ │ └── CLAUDE.md # Node 项目专属规则 └── hooks/ ├── pre-commit-check.sh └── settings.json.example你不用照搬这个结构但要理解背后的意图通用模板和项目专属模板分开各类资源按技术栈组织方便按需复制。维护模板库的过程中我逐渐把它当成一个真正的软件项目来对待有版本号、有变更记录、有配套的说明文档。这比零散地往各项目里塞文件要可持续得多。4. 模板踩坑记录与排查速查表搭建和使用 claude-code-templates 这段时间我没少踩坑。有些问题特别隐蔽排查起来花了不少时间这里整理出来希望能帮你少走弯路。4.1 规则冲突AI 不知道听谁的这是最常见的问题。比如 CLAUDE.md 里写着所有错误码必须登记到 errors.md但某个斜杠命令里没有提到这一点AI 在执行这个命令时可能就把这条规则忽略了。根本原因是模板里的规则并不是自动叠加的AI 是综合所有上下文做判断规则不明确、前后矛盾时它就会按照自己的理解来。解决办法是在模板头上加优先级说明。我习惯在 CLAUDE.md 第一段写# 模板优先级 本条 CLAUDE.md 是项目最高约束斜杠命令中的指令只限定单次任务如果两者冲突以 CLAUDE.md 为准。这不保证 AI 百分之百遵守但实测下来它能显著降低规则冲突时的随机性。4.2 上下文被无关的模板内容撑爆模板不是越大越好。我曾经见过有人把上千行编码规范全写进 CLAUDE.md结果 AI 每次会话都要处理一大堆低价值文本不仅开机响应变慢还会因为上下文被占用而忽略真正重要的任务上下文。这有点像往背包里塞满东西真正要拿的那件小物品反而翻不出来了。优化办法是分层。全局~/.claude/CLAUDE.md只放最通用的个人偏好项目 CLAUDE.md 只放项目特有信息其余的详细规则拆到独立的 slash command 和 agent skill 里按需加载。这样 AI 在判断是否加载某部分内容时自由度更高不会把整个模板库一次性读进上下文。4.3 命令文件描述不准确AI 启用不了技能前面提过Claude Code 很多时候是根据 description 来决定是否使用某个命令或技能的。我一开始没当回事写 description 特别随意比如description: code review结果 AI 在真正需要代码审查任务时并没有主动触发这个命令。后来我学会了一个更具体的写法--- description: 对未提交的 git diff 执行安全审查与代码风格检查并输出 pass/fail 结论和修复建议 ---这里的关键是让 AI 能把它正在做的任务和命令功能对上号。你越明确它越容易决策。这个原则对所有模板内容都适用好的模板描述应该是可被匹配的而不是看起来正确的。4.4 问题排查速查表我把遇到较多的几类问题和一个简单的排查思路整理成表格方便你遇到类似情况时快速定位现象可能原因处理建议AI 不遵守 CLAUDE.md 里的某些约定约定表述过于模糊或与命令内容冲突把约定改成明确动作并在 CLAUDE.md 开头声明优先级斜杠命令调用了但没有预期效果命令文件里缺少明确步骤或上下文信息检查命令文件是否引用了项目目录、变量是否包含足够步骤模板太杂导致响应变慢过多内容被当作默认上下文加载分层维护把非核心规则改成按需加载的命令或技能hook 没有触发事件名或 matcher 写错或脚本路径不对核对 settings.json 中 hook 的事件名称用命令行参数手动测试脚本团队其他人用模板后行为不一致各人本地版本不一致或全局 CLAUDE.md 不统一模板库纳入 Git 管理并约定同步时机和更新流程5. 让模板跟项目一起进化而不是一劳永逸模板库最难的地方不在搭建在于后续维护。很多人的模板库建完就吃灰过两个星期再打开发现里面的命令已经不适用于新流程了。拿我自己的经验来说真正的维护动作不是定期检查文件而是从日常使用中回收经验。5.1 从真实对话里回收模式我现在的习惯是每过一段时间翻看 Claude Code 的会话记录特别关注那些同样的任务我重复修改了好几次提示词的过程。这些反复微调的内容往往就是下一批模板命令的素材来源。比如我经常在让 AI 生成迁移脚本后还要手工补一段回滚逻辑后来就把迁移脚本必须同时生成 upgrade 和 downgrade写进了 new-migration 命令。这种模式提炼不是靠坐在那里头脑风暴而是靠复盘真实使用过程。5.2 团队评审模板变更如果模板库是团队共用切忌一个人悄悄改完后直接推到所有项目。Claude Code 的行为会因为模板的变化发生显著改变一条看起来无害的命令可能会影响别人的日常操作。我在团队里会拉一个轻量评审流程模板变更先提 PR简单描述为什么改、影响面是什么通过后再同步。这步骤看起来慢实际维护成本和返工成本都低很多。5.3 保持最低可用原则最后再分享一个我反复强调的原则模板库永远只保留解决实际问题的最小集合。每当你产生这个情况以后可能用到的念头时就先不要写进去等它真的发生三次以上再考虑固化成模板。模板不是知识库它不是用来收藏的而是用在每次会话里减少决策和重复劳动的。留下的每一条规则都应该能回答这个问题没有这条规则AI 会在什么场景下犯错从我个人实际操作体会来看claude-code-templates 最有价值的产出不是那些 Markdown 文件本身而是逼着你梳理清楚了自己的工作流程。当你把模糊的习惯变成明确的规则把规则变成 AI 自动加载的操作手册你才真正开始用管理者的思路去使用 AI 工具而不是一次次做它的临时讲解员。