Claude Code 模板体系实战：从 CLAUDE.md 到 hooks 的完整工程化指南

用Claude Code半年多我做过最值的一件事就是把前三个项目里反复踩的坑、反复写的指令、反复调的参数沉淀成了一套claude-code-templates。如果你也在用 Claude Code 写项目或者正准备开始用这份沉淀下来的模板体系和实操笔记应该能帮你少走不少弯路。先说清楚这套东西能干什么它不是一份简单的提示词锦集而是一套让 AI 理解项目、约束行为、复现工作流的完整骨架。解决了三个最头疼的问题——每次新项目都要从零调教 Claude、多人协作时 AI 的代码风格因人而异、以及 AI 偶尔自作主张改不该改的文件。适合的人群很明确正在用 Claude Code 写真实项目的开发者、想给团队引入 AI 编码助手的技术负责人、以及被AI 写出烂代码/乱改结构折磨过的朋友。1. 为什么你需要一份 Claude Code 模板而不是一堆 Prompt很多人第一次接触 Claude Code 时的姿势是装好命令行工具然后开始用自然语言发号施令。帮我写个登录接口重构一下这段代码听起来很爽但实际用下来你会发现——同一个 Claude 模型在 A 项目里表现惊艳换到 B 项目就水土不服。1.1 裸用 Claude Code 的三大痛点第一个痛点是项目上下文缺失。Claude Code 虽然能读取仓库文件但它不知道你的业务背景、架构决策、代码约定。它写出来的代码单看语法没问题一放进你的系统里就格格不入——命名风格不对、工具函数不用、异常处理模式跟项目规范不一致。这就像请了个很聪明但完全不了解你公司的新员工你得一遍遍解释背景它才能进入状态。第二个痛点是上下文窗口被无效内容占满。裸用的时候每次对话都要把项目信息重新喂一遍。我今天上午就见过一个同事为了让 Claude 写一个 API 封装把数据库表结构、接口文档、历史代码贴了三千多行进对话里。结果 Claude 的回答还没他提问长。这不是模型不行是你没给它一个高效的信息组织机制。第三个痛点是行为不可控。Claude Code 有执行命令、修改文件的权限裸用的时候它可能顺手改了.gitignore、把依赖升了级、或者自作主张重构了一个你根本不想动的模块。这个我在 1.2 节会详细讲怎么规避这里先说结论你需要一套预设的指挥边界告诉 AI 什么能碰、什么不能碰。1.2 模板化到底解决了什么本质问题模板化的本质是把你脑子里的项目知识和你期望的 AI 行为模式固化成可复用的文件。一旦建好后续所有关于这个项目的对话都会自动加载这份共识你不用每次重复交代。我打个比方裸用 Claude Code 像是每次打车都跟司机解释路线遇到健谈的司机还得纠正他别绕路用了模板系统之后等于给你的车装上了固定的导航路径——司机Claude上车就知道该走哪条路、哪里要减速、哪里禁止转弯。你的对话可以直接说出发吧剩下的交给模板约束。这套模板体系我拆分成了四个层次每个层次解决一类问题层次对应文件解决的问题项目理解层CLAUDE.md让 AI 看懂技术栈、架构、术语、命令角色行为层agents/下的角色文件让 AI 按特定角色输出PM 写的需求文档就是有条理交互效率层.claude/commands/下的斜杠命令把高频指令封装一条命令触发完整流程安全约束层hooks 配置在 AI 动手前拦截危险操作这套分层不是拍脑袋想的。我最初只写了CLAUDE.md后来发现它管得住写什么管不住怎么写又加了角色文件结果 AI 行为是规范了但每次发指令还是啰嗦最后补上斜杠命令和 hooks才算真正达到了开箱即用的效果。下面逐一拆解。2. 模板体系的骨架CLAUDE.md 到底该怎么写CLAUDE.md是 Claude Code 的入口文件放在项目根目录类似 Cursor 的.cursorrules但更体系化。这个文件的意义相当于给新员工发一本《员工手册》——先讲清楚公司文化再说工作流程最后划红线。2.1 CLAUDE.md 的黄金结构我见过很多人的CLAUDE.md就是个场景列表堆了二三十条指令什么你是一个资深 Python 工程师请写出高质量的代码。这种文件 AI 会读但读了跟没读一样——太泛没有任何项目特定信息。我总结的黄金结构分六块每块都有实际作用# 项目概述3-5句 这个项目解决什么问题、当前处于什么阶段、核心业务逻辑是什么 # 技术栈与架构地图 用到的语言、框架、关键依赖目录结构说明数据流方向 # 关键术语与业务概念 项目中特有的名词、缩写、领域词汇的统一解释 # 常用命令 测试、构建、lint、启动开发服务器的确切命令 # 代码规范与约束 命名习惯、错误处理风格、禁止使用的模式、需遵循的架构原则 # 已知问题与禁忌清单 这个项目的雷区、历史踩坑记录、AI 容易出错的地方关键在最后两块。代码规范我单独强调一下你不需要把公司所有 lint 规则抄进去只写 AI 容易搞错、且会导致返工的那些。比如我们项目里明确写了所有数据库操作必须走 repository 层禁止在 service 里直接写 SQL新代码一律使用async/await禁止.then()链式调用——这两条就是实实在在踩过坑才写进去的。2.2 我的一份实际 CLAUDE.md 内容参考这里贴一份我实际在用的模板脱敏后的通用版你可以直接拿去改。这是一个 Node.js TypeScript 的 Web 后端项目# 项目概述 XX订单系统提供订单创建、支付回调、对账查询三类核心接口。当前处于 v2 重构阶段新旧接口并存。业务核心是订单状态机流转所有状态变更必须经过订单服务统一处理。 # 技术栈与架构地图 - 运行时Node.js 18TypeScript 5.xstrict 模式开启 - Web 框架Fastify路由注册在 src/router/ 下按域划分 - 数据层Prisma PostgreSQL所有 schema 变更需通过 migration 文件 - 目录结构 - src/domain领域模型与状态机定义 - src/repository数据库访问层唯一允许写 SQL 的地方 - src/service业务逻辑层调用 repository - src/api接口路由与参数校验层只做转发和校验 # 关键术语 - 主单/子单一个主单对应多个子单子单状态汇总后同步到主单 - 关单订单关闭操作关闭后不可再支付但保留只读查询能力 - 幂等键支付回调必须携带相同幂等键重复请求只处理一次 # 常用命令 - 本地开发pnpm dev - 跑测试pnpm test单元测试 集成测试一起跑 - 构建检查pnpm build含 tsc 类型检查必须 0 error - 代码检查pnpm linteslint prettier 一起跑 # 代码规范 - 所有数据库操作必须走 src/repository 层service 层禁止直接调用 Prisma client。 - 接口入参校验使用 Fastify schema不写手动 if 判断。 - 错误处理业务错误抛出 BizError(code, message)由全局 error handler 统一返回。 - 新增文件必须有对应的单元测试覆盖正常路径和至少一条异常路径。 # 已知问题与禁忌 - 订单取消和关单是两个不同流程AI 经常混淆取消是用户主动关单是系统超时。 - 不要修改 src/domain/order-status.ts 里的状态枚举值有 30 外部依赖。 - 支付回调是高频接口严禁加同步的数据库写操作只能投递到消息队列。 - 历史代码中 src/utils 下有个老旧的 http.ts只读禁止调用。 # 初始化 1. pnpm install 2. cp .env.example .env 3. pnpm db:migrate 4. pnpm dev这份文件看起来长但 Claude Code 会把它作为每次会话的初始上下文自动加载信息密度高一点没关系关键是条理清晰。写完这份文件你再让 AI 写代码它写出来的东西会明显收敛到你的项目体系里——因为它知道你这套项目的规矩了。3. 角色模板与斜杠命令让 AI 不只是会写代码CLAUDE.md解决了懂项目的问题但实际操作中你面对的任务千差万别——有时候需要 AI 当架构师帮你想方案有时候需要它当测试工程师补用例有时候需要它当代码审查员挑毛病。不同角色的输出风格和思维模式完全不同这就是角色模板agents的用武之地。3.1 如何用 sub-agents 给 AI 装人格切换开关Claude Code 支持通过.claude/agents/目录定义多个角色的 AI。每个角色文件就是一个 Markdown 文档定义角色的人设、职责边界、工作流程。我看过很多团队写的 agent 定义最大的问题是想做的事太多。一个 agent 文件里又让 AI 写代码又让 AI 审查代码又让 AI 写文档结果什么都干不好。好的 agent 定义一定要职责单一、边界清晰。我实际维护了四个角色文件其中最有价值的是code-reviewer它解决了让 AI 审查 AI 写的代码这个核心痛点# Role: Code Reviewer 你是项目里资深的代码评审工程师工作风格严格但不刻薄。你的唯一职责是审查代码变更找出问题并给出修复建议不负责直接修改代码。 ## 审查流程 1. 读取变更涉及的文件理解业务意图 2. 对照 CLAUDE.md 中的代码规范和架构约束逐项核查 3. 检查异常处理、边界条件、幂等性、并发安全 4. 输出审查报告按严重级别标注问题 ## 输出格式 用 Markdown 列表输出每项包含 - 问题位置文件:行号 - 问题类型规范违反/逻辑缺陷/性能隐患/边界遗漏 - 严重级别Blocking / Important / Suggestion - 具体说明和修改建议 ## 红线 - 不使用In my opinion这类模糊措辞给结论要直接 - 不讨论代码风格偏好只以项目规范为准 - 不提出超出本次变更范围的修改建议有了这个角色文件我在命令行里输入/review加上改动范围Claude 就会切换到审查模式。跟裸用时候最大的区别是它会严格要求自己对照规范逐条检查而不是凭感觉说这段代码不错。3.2 把高频任务封装成斜杠命令角色文件管人格斜杠命令管流程。.claude/commands/目录下的每个.md文件对应一个斜杠命令。我封装最频繁的几条命令分享出来/feature命令触发一个完整的新功能开发流程。它会先根据你的描述整理需求再拆解任务、逐个实现、补充测试、更新文档。在裸用状态下你得一步步提示 AI先分析需求、再设计接口、再写实现...现在一条命令全搞定。/fixbug命令专治帮我看看这个 bug。它要求 AI 先复现问题、定位根因、再给修复方案重点在于禁止 AI 直接改代码而是先输出分析和方案让你确认。这个约束救了我不止一次——AI 直接改代码时经常引入新问题先出方案我审核后再说风险小得多。/test命令它会根据代码变更范围自动生成对应的测试用例而不是笼统地写测试。实际用下来AI 生成的测试质量跟它理解需求的程度成正比。你的CLAUDE.md写得越到位生成的测试就越有针对性这是强相关的。命令文件的格式很简单核心是description和触发后的指令内容。以/fixbug为例--- description: 定位并修复 bug先分析根因确认后动手 --- 你是一名资深调试工程师。请先运行项目测试并观察是否复现问题然后按以下步骤处理 1. 要求用户描述 bug 现象、期望行为、实际行为 2. 阅读相关代码定位根因并输出根因分析 3. 暂缓修改代码输出修复方案等待用户确认 4. 用户确认后实施修复并补充对应测试用例 5. 运行相关测试确认通过后总结变更 如果无法复现直接输出无法复现并列出可能的环境因素不要强行修改。斜杠命令还有一个隐藏好处命令行里敲/就能看到所有命令列表团队新成员接入项目时看一眼列表就知道 AI 能做哪些事比读文档直观多了。4. 安全围栏hooks 配置——模板里最容易忽略但最救命的部分前面聊的都是怎么让 AI 干得更好这一节聊怎么防止 AI 干坏事。Claude Code 的 hooks 机制提供了在工具调用前后执行自定义检查的能力相当于给 AI 的动作加了安全护栏。4.1 三条我强烈建议配置的 hook 规则用 Claude Code 时间久了你会发现AI 偶尔会做出低级但致命的操作——比如提交了一半没写完的代码到 git、在迁移环境里执行了生产数据库的 drop 语句、或者手滑格式化了整个目录。hooks 就是为拦截这类操作设计的。第一条是保护 git 操作。在 PreToolUse 阶段拦截git push到生产分支#!/bin/bash # 保存为 .claude/hooks/pre-tool-use-git.sh if [[ $TOOL_NAME Git $TOOL_INPUT *push* $TOOL_INPUT *origin main* ]]; then echo 检测到对 main 分支的 push 操作已阻止。请先创建分支提交合并请求。 exit 2 fi echo ✅ Git 操作安全 exit 0这里exit 2是 Claude Code 约定的阻止操作信号AI 会收到拦截通知并重新安排下一步动作。这样能防住 AI 在你的 agent 配置里偷偷加个自动部署到生产的动作。第二条是临时文件检查。AI 经常为了快速验证逻辑在项目根目录留下test.js、temp.py、scratch.py之类的文件污染仓库。在 PostToolUse 阶段检查新文件列表如果发现不符合命名规范的临时文件就报警提醒。第三条是敏感信息扫描。在 AI 读取文件或写入文件时用 grep 扫描是否出现api_key、password、access_token等字符串一旦发现代码里混入硬编码密钥立刻阻止继续执行。这比事后让人工审查可靠得多——AI 可不会觉得自己把密钥写进代码有什么问题你得提前组织它。4.2 配置 hooks 的几个注意点hooks 脚本的编写有一些细节容易踩坑我列几个实际遇到的问题注意点一脚本环境要自包含。hooks 脚本运行在一个干净的 shell 环境里PATH 可能跟你本地环境不一样。不要假设git、python一定在 PATH 里脚本开头最好显式声明环境变量或者用绝对路径。我踩过一次坑脚本里用了jq解析 JSON结果部署机器上没装 jqhook 直接报错了。注意点二hook 的退出码要设计好。Claude Code 的约定是0表示通过2表示阻止其他非零值表示错误。很多人把1当作阻止用结果 AI 把1当成执行出错而不是被拦截转而尝试换一种方式继续操作反而绕过了安全检查。统一用exit 2语义清晰。注意点三hook 脚本的日志要区分 AI 可见和不可见。脚本输出到 stdout 的内容会作为提示发回给 AI。像⚠️ 阻止了对 main 分支的 push这类信息让 AI 看到没问题但如果你在脚本里打印了密钥内容、内部路径等敏感信息就等于把这些白送给 AI 当上下文了。建议敏感信息输出到 stderr 或日志文件而非 stdout。5. 模板的迭代与管理一份模板如何演变成一套工程实践最后聊一聊我是怎么维护这套模板体系的。很多人的模板写完之后就再也不动了这是很大的浪费——模板应该是活的在你使用 AI 编码的过程中持续更新就像优秀的开源项目会持续迭代一样。5.1 把踩过的坑写回模板——建立反馈闭环我给自己定了一个规则每次被 AI 坑了一次就在模板里加一条约束每次发现 AI 通过某条提示表现得特别好就精简模板给 AI 更多自主空间。这个规则用起来效果特别好。举个例子有次 AI 改变了我们项目的接口路径结构理由是为了更好的 RESTful 风格。技术上讲它没错但我们前端路由已经写死了改路径等于让前端一大片代码返工——这就是个典型的AI 理解规范但不理解业务上下文的案例。我后来在CLAUDE.md的禁忌清单里加了一条禁止修改现有接口路径除非用户明确要求。API 兼容性优先于接口美观。加上这条之后同样的问题再没出现过。这个反馈闭环的思路你也可以复用把 AI 出错当成免费的项目咨询它用它的方式暴露了你项目中文档化不足、规范不清晰、架构边界模糊的地方然后你把修正固化进模板形成正向循环。5.2 多仓库管理模板的两种实践如果你只有一个项目模板文件放在仓库里就行。但只要有两个以上项目模板管理就变成了一件需要设计的事。我的做法是模板文件分两层templates/ 模板的原始源独立仓库维护 ├── base-claude.md # 所有项目通用的基础规范 ├── agents/ │ ├── code-reviewer.md │ ├── tech-writer.md │ └── debugger.md ├── hooks/ │ ├── pre-tool-use-git.sh │ └── post-tool-use-temp-file.sh └── commands/ ├── feature.md └── fixbug.md my-project/ 具体项目拷贝或软链模板 └── .claude/在项目里我是用脚本从模板仓库拷贝到各项目目录的带一个简单的版本标记。模板仓库里改了什么项目里更新时会有 diff 提示我人工过一遍再合并。这样既保留了统一性又留了个性化空间——每个项目可以在基础模板之上追加自己的特殊约束就是前面那份 CLAUDE.md 的六段式结构里涉及的个性化部分。5.3 针对团队推广的一点经验如果要把这套体系推广给团队最大的挑战不是技术而是信任。团队其他成员不一定认同给 AI 定一堆规矩这件事有人会觉得这是过度设计有人会觉得模板限制了 AI 的灵活性。我的建议是不要一上来就全量铺开而是挑一个大家都痛的点切入。比如先只上 code-reviewer 这个角色让大家体验一下让 AI 做代码 review 的效果前提是 AI 靠谱跑两周之后大家尝到甜头了再逐步把 CLAUDE.md、hooks 引进来。实践是最好的说服数据比理论管用。另外模板文件一定要给团队成员留一个feedback入口。我在模板里加了一段注释发现 AI 行为有任何异常欢迎把触发条件发到群里维护者来更新模板。这样模板迭代就不只是一个人的事而是一个团队的经验沉淀了。6. 常见问题与排查技巧实录最后这部分整理一下我在这套模板实践中最常遇到的问题以及对应的解决办法。这些问题如果你也遇到了按下面的方式排查大概率能省不少时间。6.1 AI 好像没读到模板内容怎么办很多人写了CLAUDE.md但发现 AI 行为完全没变化。这里有个关键点Claude Code 是按会话加载上下文的如果模板是在会话进行到一半时才创建的当前会话可能不会自动加载。解决方案有两种一是重启 Claude Code 会话退出重进让模板加载二是检查模板文件是不是放在了正确位置——CLAUDE.md必须在项目根目录.claude目录同理。还有一种情况是权限配置问题。Claude Code 有个--allowedTools的配置如果模板里设计了某些工具调用但你没有在权限列表里放行AI 会直接跳过模板里的步骤而不是执行。排查方式在交互界面输入/status查看当前可以调用的工具范围确认模板涉及的权限已开放。6.2 模板写得越来越长AI 变迟钝了怎么破这是一个典型的过度设计问题。模板越长AI 的上下文占用越高响应变慢还在其次更严重的是它会迷失重点——满屏都是规则时它分不清什么才是当前任务最该遵守的。我的经验法则是模板文件总字数控制在 1500 字以内CLAUDE.md 部分agent 角色文件每个在 500 字以内。超出这个体量就要考虑是不是有些内容可以挪到命令文件里按需触发而不是放进长期上下文。像如何发布到测试环境这种低频操作做成/deploy-test命令按需用比长期占着上下文划算得多。精简模板还有一个额外技巧定期看 Claude Code 的 token 消耗统计。如果你发现最近几天的 token 消耗异常增高往往意味着模板里有大量内容在每次会话中反复重复——该精简了。6.3 hooks 脚本报错但 AI 没被拦住hooks 分 PreToolUse 和 PostToolUse 两种。如果你在前置PreToolUse规则里拦截但 AI 已经成功执行了大概率是 hooks 的路径配置不对。Claude Code 的 hooks 配置文件是.claude/settings.json不是直接丢个脚本就能生效的。你需要在这个 JSON 里声明 hook 对应哪个阶段、执行哪条命令{ hooks: { PreToolUse: [ { matcher: Git, hooks: [ { type: command, command: .claude/hooks/pre-tool-use-git.sh } ] } ] } }matcher字段是匹配工具名称的Git只拦截 git 操作Edit拦截文件编辑操作。如果 matcher 写错了你的 hook 压根不会触发这通常是问题所在。6.4 团队里不同成员的模板不一致项目模板是放在.claude/目录的如果这个目录被加进了.gitignore就会出现我的机器上有模板同事机器上没有的尴尬情况。我建议模板目录必须提交到代码仓库包括 hooks 脚本和 agent 文件。团队成员各自有本地修改的话用 git merge 解决冲突即可这样至少保证了模板有一个权威的主干版本。同时需要注意.env之类的敏感文件不要放进.claude/目录也不要在 hooks 脚本里读取.env的内容否则提交仓库时容易凭白制造安全隐患。hooks 脚本涉及密钥读取的应当通过环境变量注入而不是写在脚本里。6.5 模板写好后如何验证有效性最后分享一个自检方法。每次大幅修改模板后我会做一次模板体检开一个新的 Claude Code 会话发一条模拟指令比如帮我写一个新的接口参照现有代码风格看 AI 第一步是不是主动阅读模板、引用项目规范检查输出代码是否符合规范里的强制项人为触发一次危险操作比如让它删除.env测试 hooks 会不会拦这套验证流程走通之后再放开给团队用。模板不是一次性的它最宝贵的部分是能跟着项目一起进化——项目难在哪里模板就长在哪里这样你每次和 AI 的配合都会变得越来越顺手。