我维护自己的 Claude Code 模板仓库已经快半年了从最开始在会话里随手贴一段 prompt到后来把所有高频操作都沉淀成 claude-code-templates算是把这条路完整走了一遍。这篇文章不是讲某个库的 README而是把我整理的模板结构、命令脚本写法、hooks 设计思路全部拆开讲适合已经用过 Claude Code、想把它变成团队生产力工具的人也适合刚接触这个工具、想一步到位搭好工作流的开发者。直接说结论模板的意义不是省几行字而是让 AI 的行为可预期。没有模板每次对话都是一次新的掷骰子有了模板至少你投喂给模型的上下文是稳定、结构化的。下面按我在实际项目里沉淀模板的顺序逐个模块讲透。1. 为什么在 Claude Code 工作流里模板比提示词更重要1.1 从每次重写 prompt到模板驱动我最早用 Claude Code 的时候动辄在终端里敲上千字的上下文项目架构、技术栈、目录结构、注意事项、本次任务目标。一次两次还能忍受等任务多了就会发现几个问题一是相同的信息重复描述口径还不一致。比如我一开始写后端是 Python 3.11 FastAPI后一次改成Python 3.12 FastAPI模型可能就把两个版本都当成事实混在一起处理。二是每次会话都要重新教育模型项目规则真正干活的时间被压缩。三是团队里每个人给 Claude 的指令风格完全不同A 让模型写单测B 让模型写文档出来的代码风格和质量完全不可控。claude-code-templates 解决的就是这三个问题。它本质上是一个工程目录按照 Claude Code 的约定把项目规则、命令脚本、辅助脚本、参考资料全部塞进去。只要你把这个仓库克隆下来或者作为子模块挂到项目里Claude Code 启动时就会自动读取这些模板文件把你是谁、项目是什么、该按什么规矩干活一次性交代清楚。1.2 模板库最核心的三种形态在研究 Claude Code 的配置机制后我把模板分成三个层次分别对应不同生命周期模板类型存放位置作用加载时机CLAUDE.md项目根目录定义项目常识、命令、架构每次会话自动加载斜杠命令模板.claude/commands/实现具体工作流如 code review、补测试、写提交信息用户在输入框触发/命令名Hooks 脚本.claude/hooks/在特定事件前后拦截或校验如PreToolUse、PostToolUse事件触发这三个层次各有分工CLAUDE.md 解决AI 知道什么命令模板解决AI 能做什么hooks 解决AI 做错之前怎么挡下来。我见过不少人的 template 仓库里只有 CLAUDE.md命令目录和 hooks 目录空着等于只用了 30% 的能力。1.3 什么时候模板反而是负担这个部分必须泼一盆冷水模板不是越多越好。我试过把几十个斜杠命令塞进.claude/commands结果输入/之后列表巨长连自己也记不清每个命令的用途。React 经典的太多了反而不知道用哪个问题在 AI 命令面板里同样存在。后来我把模板按高频、复用两个维度做过滤留下大约 12 个命令覆盖需求拆解、代码审查、单测生成、重构、提交信息生成这几个刚需场景。另外模板文件里的描述如果写得过于抽象模型对命令的理解就会飘。比如你的命令模板里写对代码进行全面优化模型可能不知道边界在哪里容易乱改代码。模板文字越具体、约束越明确实际执行效果越好。2. CLAUDE.md 是项目记忆层先把类型化知识固化下来2.1 CLAUDE.md 的自动加载机制Claude Code 启动时会从当前目录向上查找 CLAUDE.md并把它作为系统上下文的一部分加载。这意味着它不需要你手动引用模型在回答任何问题之前就已经看过这份文件。这是整个模板体系中最基础的机制也是很多人用不好的一环。CLAUDE.md 的内容不是给人类看的 API 文档而是给 AI 看的项目入职手册。写它的思路应该跟给新同事写 onboarding 文档类似但节奏要更紧凑因为模型对长文本的注意力是有上限的。如果你把 CLAUDE.md 写成 5000 字的需求文档它反而可能忽略关键信息。2.2 一份高复用 CLAUDE.md 模板的段落结构我在 claude-code-templates 里维护的 CLAUDE.md 模板固定分为六段# 项目识别信息 项目名称xxx-service 技术栈Python 3.12 / FastAPI / PostgreSQL 16 / Redis 7 语言项目注释、提交信息、PR 描述一律使用中文 # 架构与目录约定 src/api 放路由src/services 放业务逻辑src/models 放 SQLAlchemy 模型 禁止在 api 层编写业务逻辑 新增数据库迁移必须同时更新 docs/migrations/CHANGELOG.md # 命令与运行方式 启动poetry run uvicorn app.main:app --reload 测试poetry run pytest tests/ -q --no-header 代码风格ruff check src/ ruff format src/ # 现有约定与样式 日志使用 structlog格式为 JSON 异常码统一使用 BUSINESS_XXX禁止直接抛裸 Exception 所有接口返回统一包装为 {code, message, data} # 注意事项 - 禁止修改 alembic/versions 下已提交的迁移文件 - 生产环境配置只允许通过环境变量注入不放进代码仓库 - 删除代码前先搜索是否有引用破坏性变更必须同步更新 README # 当前任务会话结束后清空 在这里描述本次会话的具体目标避免污染长期规则最后这行当前任务是我后来加的用来区分离散任务和长期规则。CLAUDE.md 是持久的状态而任务是一次性的如果直接把任务写进 CLAUDE.md后几次会话它会把旧任务当成项目规则正确率会下降。2.3 常见写法误区把 TODO 写进去、把代码示例写太长写 CLAUDE.md 最容易踩的坑我列几个实际观察到的。第一个是把 TODO、下周计划、未完成需求写进去。模型无法区分事实和待办你写计划接入消息队列它可能在下一次会话时直接告诉你系统已经接入了消息队列。解决办法是新建一个project-status.md通过project-status.md手动引用而不是写进 CLAUDE.md 自动加载。第二个是代码示例过多。CLAUDE.md 里每贴一段代码模型都会在生成代码时倾向于复刻这段代码的风格和字段如果示例已经过时会把旧 API 带出来。我后来把代码示例精简到每个场景不超过 10 行并明确标注参考结构不要直接复制。第三个是把 CLAUDE.md 当作唯一的知识来源。实际上一旦工程规模变大所有内容硬塞一份文件模型加载起来非常吃力。更合理的做法是 CLAUDE.md 只写高置信度的稳定规则其余知识分散到 docs 目录通过额外的docs/xxx.md引用按需加载。3. 斜杠命令模板把高频操作变成可复用的工作流快捷键3.1 命令文件的位置与 YAML frontmatterClaude Code 的斜杠命令本质上是一段带元信息的 Markdown 或脚本文件。把文件放到.claude/commands/目录下文件名去掉扩展名就是命令名。比如.claude/commands/review.code.md触发/review。每个命令模板文件的开头必须包含一段 YAML frontmatter至少定义description和argument-hint。description很关键因为当你输入/时Claude Code 会用它做模糊匹配argument-hint则是一段提示文本告诉模型用户传给这个命令的参数长什么样。--- description: 审查当前分支的改动给出按严重程度排序的问题清单 argument-hint: [可选指定审查范围如 src/api, src/services] ---正文部分就是你的指令。这里有个技巧把指令写成规则 输出格式 约束三块比单纯让模型检查代码问题效果稳定得多。3.2 我在 pr-review.code 模板里怎么设计拿我最常用的pr-review.code.md举例它是专门用来审查 MR/PR 的# 角色与目标 你是资深代码审查者只基于项目 CLAUDE.md 与当前分支 diff 进行审查不臆测需求。 # 审查流程 1. 运行 git diff --stat 了解改动范围 2. 重点检查安全漏洞、数据一致性、错误处理、破坏性变更、测试覆盖 3. 如果 diff 超过 800 行按模块分批审查先输出总体结论 # 输出格式 按严重程度分三类输出 - **阻塞**可能导致线上事故、数据错误、安全风险 - **建议**可维护性、性能与扩展性改进不影响合并 - **细节**命名、注释、格式化等非阻塞问题 每个问题必须包含文件路径、起始行号、问题描述、最小化修复建议。 # 约束 - 不修改任何代码文件只输出审查结论 - 不重复已知的 lint 错误如 ruff、eslint 可直接定位的问题 - 如果已有自动化测试通过则不再建议补充无关单测这个模板用了三个关键设计。一是基于 diff 而不是整库分析审查速度会快很多也不会被无关代码带偏。二是按严重程度分三类这样模型不会把格式问题和业务逻辑问题混在一堆输出里我拿到结论后可以直接决定如何处理。三是不重复已知 lint 错误这是防止模型输出低质量噪音的过滤条件。3.3 多级参数校验与增量输出后来自从我发现 Claude Code 的命令模板支持内嵌脚本执行后我开始在命令模板里混合使用 Markdown 指令和 bash/python 片段。这样做的核心收益是可以做参数校验和上下文预加载。比如我的/follow-up命令作用是基于上一次会话继续开发。模板里会内嵌一段 bash 脚本把最近一次会话的摘要文件路径读出来然后用cat拼接给模型# 自动读取最近会话摘要 if [[ -f .claude/session-last.md ]]; then cat .claude/session-last.md else echo 警告未找到会话摘要文件本次基于当前代码库状态继续 fi这比让模型自己去翻历史对话可靠得多。因为 Claude Code 会话之间不会自动共享上下文你把状态文件当作中间媒介模板脚本负责载荷模型只负责处理分工非常清晰。如果你在团队里使用这套模板建议在命令模板里明确输出边界例如只输出结论不输出思考过程的命令如审查类允许展示推理过程分析的命令如排查 bug 类直接执行修改类命令如格式化、生成文件名列表4. 参考文档模板和 hooks让规范自动生效4.1 把技术规范、依赖矩阵做成可检索常识库CLAUDE.md 能承载的知识量是有限的。项目里的规范文档、依赖清单、环境变量说明、部署流程这些内容如果都写进 CLAUDE.md既冗长又难以维护。我的做法是把这些内容拆成独立文档存在CLAUDE-reference/目录下然后在 CLAUDE.md 里只放一份索引表。# 参考文档索引 - CLAUDE-reference/dependencies.md —— 依赖版本与升级注意事项 - CLAUDE-reference/api-design.md —— 接口设计规范与状态码定义 - CLAUDE-reference/migration-guide.md —— 数据库迁移流程与回滚方案 - CLAUDE-reference/production-runbook.md —— 生产部署、健康检查、常见故障这样模型在需要的时候通过引用精准加载而不是把所有文档一股脑读进上下文。依赖矩阵是我个人最喜欢用的一个模板| 依赖 | 当前版本 | 可升级版本 | 升级风险 | 备注 | | --- | --- | --- | --- | --- | | fastapi | 0.115 | 0.116 | 低 | 仅小版本更新 | | pydantic | 2.9 | 2.11 | 中 | 需检查自定义泛型 | | sqlalchemy | 2.0.36 | 2.0.40 | 低 | 无破坏性变更 |模型拿到这个表之后当发生变化时就能自动意识到升级有风险要先查迁移说明而不是盲目建议升级依赖。4.2 hooks 模板在错误发生之前拦截hooks 是 Claude Code 比较容易被忽略的能力。它在 AI 调用工具、生成内容、会话结束等节点可以触发脚本实现精确控制。我常用的三个 hooks 模板PreToolUse在 AI 准备执行危险命令前拦截。比如检查命令是否为rm -rf、DROP TABLE、git push --force命中则阻断要求模型先向用户说明修改计划。PostToolUse在 AI 执行完工具后校验输出。比如git diff之后检查是否改动了锁定文件。Stop在每次生成暂停时把当前状态追加到.claude/session-last.md方便后续会话延续。拿PreToolUse的钩子脚本举例以 bash 模板#!/usr/bin/env bash set -euo pipefail json_input$(cat) # 提取工具名称和参数 tool_name$(echo $json_input | jq -r .tool_name) command_str$(echo $json_input | jq -r .tool_input.command // ) # 定义危险命令黑名单 if [[ $tool_name Bash ]]; then case $command_str in *DROP TABLE*) echo {decision: block, reason: 禁止直接执行 DROP TABLE请输出迁移 SQL 并交由人工执行} 2 exit 2 ;; *rm -rf*) echo {decision: block, reason: 检测到 rm -rf阻断高危删除操作} 2 exit 2 ;; esac fi # 默认放行 echo {decision: allow} 2 exit 0这个脚本的结构非常直白读 stdin 拿到 JSON 参数判断工具是否命中黑名单然后向 stderr 输出决策结果。注意输出格式是 JSON并且一定要2这是因为 hooks 的决策信息走的是错误输出通道混入 stdout 会导致 Claude Code 解析失败。把这些 hooks 放进.claude/hooks/后AI 触发的危险操作就会被自动拦截。这套东西在公司里的价值尤其明显因为新同事不熟悉项目约束时AI 的高速生成可能带来潜在的操作风险而 hooks 是最后一道防线。4.3 团队场景下模板库的版本控制与同步最后讲一下模板库的落地问题。单个开发者维护一套模板没问题但团队协作时三天两头改模板会让大家很烦。我建议把 claude-code-templates 作为一个独立 git 仓库然后用子模块或者构建脚本的方式安装到业务项目里。具体做法是模板仓库单独建库按照目录结构维护不掺杂任何业务代码业务项目通过git submodule add 模板仓库地址 .claude把模板引入团队约定每个迭代更新一次模板子模块比如用git submodule update --remote .claude模板仓库的 CLAUDE.md 里写明变更规则比如新增命令必须附带一个使用示例避免团队成员不知道怎么用它。我还踩过一个坑一开始我把模板做成开箱即装的 npm 包直接npx一条命令安装。结果发现模板里有很多项目特定内容比如团队内部约定的异常码、接口规范这些内容根本不应该被通用分发。后来我把模板拆成两部分core部分完全通用审查流程、hooks 模板、命令骨架project部分按项目定制。通用部分才进包项目部分留在 git 子模块里。这个拆分让模板的复用性大幅提升也不怕敏感信息被传出去。我个人在实际维护中的体会是模板库不是写完就一劳永逸的东西。每当我在会话里发现 Claude 重复问同一类问题或者反复犯同一个错误我就会打开模板库把对应的规则或命令补进去。这个迭代过程比你想象中花的时间少但带来的流畅感提升非常明显。如果你也打算搭建自己的 claude-code-templates建议从 CLAUDE.md 和三个常用命令模板起步别一上来就铺开 hooks 和参考文档库先把最烦人的重复问题解决掉后面自然知道该往哪个方向扩展。