如何搭建Claude Code模板体系：从CLAUDE.md到Hooks

最近我把手头几个项目的开发流程重新梳理了一遍发现真正拉开效率差距的往往不是某个模型多聪明而是你怎么把自己项目的规矩、偏好、常用操作一次性、稳定地传递给AI。这套claude-code-templates说白了就是把Claude Code从一个能聊天的终端助手变成一个懂你项目的老同事的关键。这篇文章我会从模板体系的搭建思路、核心配置文件的写法、自定义命令与技能的定义到自动化钩子的配置完整走一遍我的实操过程。不管你是在维护大型代码库还是自己折腾开源小项目这套方法都能直接用。1. 模板体系的设计思路为什么你的Claude Code总是不够好用很多刚接触Claude Code的朋友会说这工具确实能写代码但总感觉差点意思。改代码的时候风格跟项目不一致跑命令前总要反复交代背景做代码审查时又常常抓不住项目的关键模块。这些问题十有八九不是模型能力的问题而是你压根没给它一份项目说明书。Claude Code的上下文机制决定了它是一个先有上下文、后有输出的工具。它的工作记忆来自几个地方启动时自动读取的CLAUDE.md、你手动触发的命令模板、按需加载的Agent Skills以及某些时机的自动化钩子。这套机制组合起来就是你的模板层。你喂给它的上下文越整齐、越贴近项目现实它的输出就越像这个项目的原生代码。我最早意识到模板重要是因为一次重构经历。当时我要把一个Python后端项目的所有接口从同步改成异步项目里有十来个模块各自的风格还不太一样。我试过直接在对话里反复粘贴项目结构说明但事情一多上下文就乱改到后面风格又开始跑偏。后来我把项目的架构说明、代码规范、常用的异步模式都写进了CLAUDE.md又配了几个命令模板从那之后每次让它动手它都先按项目规矩走输出的代码基本不用大改。这里得说清楚claude-code-templates指的不是某一个官方模板库而是一套你可以自己搭建的配置体系。Claude Code本身提供了很好的扩展点模板的本质是把你和AI之间的对话成本提前支付掉——你花一个小时把规矩写清楚换来的是接下来每一天的工作都不用重新解释。这套体系适合谁呢首先是每天跟Claude Code打交道的开发者无论前端、后端还是数据工程只要你的项目有稳定的技术栈和风格要求模板就值得做。其次团队协作场景里一份统一的CLAUDE.md可以让所有成员共享同一套AI协作规范新人上手也更快。如果你只是偶尔用Claude Code问几个简单问题那模板的必要性没那么强但当你开始长期用它维护一个代码库这一步迟早要迈。2. 核心配置解析从CLAUDE.md到Skills的分层结构2.1 CLAUDE.mdAI的项目档案CLAUDE.md是Claude Code的开机自启文件。只要它存在Claude Code每次启动都会自动读取把它当作理解项目的基础上下文。这个文件通常放在项目根目录但你也可以在不同子目录里放局部版本让AI在进入特定模块时自动套用那套规则。比如你的项目根目录有一个全局的CLAUDE.md定义整体架构和全局规范然后在backend/目录下放一个局部的强调后端特有的技术栈约定前端目录同理。这种分层方式有效避免了一条规则管所有导致的上下文混乱。一份合格的CLAUDE.md应该包含四块内容项目简介用三到五行说清楚这个项目是什么、给谁用、核心业务逻辑是什么。别小看这段简介它决定了AI对你所有后续问题的理解基准线。技术栈与目录结构把前端、后端、基础设施分别列清楚把关键目录的职责说明白。AI知道该去哪里找代码改起来才不至于迷路。代码风格与约束命名规范、组件写法偏好、数据库操作的约定、错误处理方式等等。这是控制AI输出质量的关键区域。常用命令开发、测试、构建、部署分别怎么跑。AI在需要执行命令时会优先参考这里。我在维护一个电商后台项目时CLAUDE.md里会明确写所有数据库变更必须同时更新Prisma schema和迁移文件API响应统一使用{ code, data, message }结构状态管理只用Zustand不用Redux。这些看起来琐碎但正是这些约束让AI的输出和团队其他人保持在同一频道上。CLAUDE.md不是越满越好这点需要特别注意。它的内容会占用每次对话的上下文窗口写太多反而会稀释真正重要的指令。我通常建议控制在50行以内把必须记住的事和需要时再查的细节分开——后者适合放进命令模板或Skills里而不是全堆进CLAUDE.md。2.2 自定义命令把高频操作固定成斜杠指令Claude Code的斜杠命令机制类似论坛里的快捷指令。你在终端输入/review它就会自动执行你预先写好事后逻辑的模板不再需要你每次手工输入一大段审查要求。命令文件放在.claude/commands/目录下每个命令对应一个Markdown文件文件名就是命令名。文件头部可以加YAML frontmatter配置命令的描述、参数提示等信息。主体部分就是你希望AI执行的指令内容写法上可以非常灵活甚至支持用变量把用户输入的值塞进指令里。我给自己的模板库配了这么几个高频命令/review代码审查。自动读取当前分支的diff按我预设的维度逻辑正确性、边界条件、安全性、可维护性逐项检查输出评分和具体修改建议。/commit生成Git提交信息。按项目的约定格式生成Conventional Commits风格的commit message附带改动说明。/refactor模块重构。要求AI先分析代码结构、列出依赖关系再给出重构方案确认后才动手改代码。/test补充测试。让AI根据函数逻辑生成单元测试用例覆盖正常路径和边界条件。你可以按自己的项目需要扩展这套命令库。比如数据工程方向的项目可以配一个/pipeline命令用来检查数据管道的依赖顺序和异常处理前端项目可以配/component命令自动按团队的组件规范生成新组件的骨架代码。2.3 Agent Skills按需加载的专家模块Skills是Claude Code里一个更接近专家能力包的机制。它与CLAUDE.md最大的区别在于加载方式CLAUDE.md是常驻的而Skill是需要时才触发的。你在Skill文件里写好某个专业领域的方法论和注意事项当对话里出现相关任务时Claude Code会自动加载对应的Skill。这种按需加载的设计让AI可以在特定任务上表现得像个专家同时不会白白占用常规对话的上下文空间。一个Skill文件的核心结构包括文件头部的YAML配置定义了技能名称和描述信息主体部分则是详细的指令、方法论、示例和检查清单。描述信息要写得够具体Claude Code靠它来判断当前对话要不要激活这个技能。我常用的一个Skill是代码安全审查它包含了一套标准的安全审计流程从输入验证、认证授权、数据加密、日志脱敏等维度逐项排查并附带了常见漏洞的模式示例。每当Claude Code处理涉及安全性的代码评审任务时它就会自动激活这套方法审查报告的专业度明显提升。2.4 Hooks钩子把重复检查自动化如果说CLAUDE.md、命令和Skills都是在对话层面帮AI理解项目那hooks钩子就是在流程层面帮AI规范行为。它让Claude Code在执行某些工具操作的前后自动触发脚本或命令在流程上卡一道关。一个典型的应用场景是修改前自动跑lint让AI在准备调用工具修改文件之前先检查目标文件是否符合lint规则不符合就先指出来避免改完再被CI打回。另一个场景是提交前自动测试AI在准备执行Git提交操作之前先跑一遍相关测试测试通过才允许提交这条规则能拦截掉不少看起来没问题、一跑就挂的改动。hooks的配置写在.claude/settings.json里支持按工具类型和时间点匹配。它的价值在于强制自动化比AI自觉遵守约定可靠得多。3. 实操过程从零搭建一套可用模板3.1 目录结构与全局配置先动手把模板库的目录搭起来。Claude Code的配置目录在不同系统下位置略有差异但结构一致。我习惯在用户主目录下建立.claude/目录作为全局配置的家然后在具体项目里用项目级的.claude/目录覆盖或扩展全局配置。目录结构大概是这样的~/.claude/ ├── CLAUDE.md # 全局规则 ├── settings.json # 全局hooks与权限配置 ├── commands/ # 全局命令模板 │ ├── review.md │ ├── commit.md │ └── ... └── skills/ # 全局技能包 ├── security-review/ │ └── SKILL.md └── ...项目级别的结构类似放在你的项目根目录下。全局配置和项目配置的加载关系是项目配置优先于全局配置同名项目会覆盖全局同名项。我的经验是全局配置只放放之四海而皆准的通用规则比如通用的代码风格偏好、通用的命令命名习惯项目特有的技术栈和架构细节一定要放到项目级配置里。3.2 编写全局CLAUDE.md一份全局CLAUDE.md最重要的是克制。它不需要关心你某个项目的技术栈只需要定义你作为一个开发者的通用偏好。比如# 全局开发偏好 - 代码改动保持最小化不做无关重构。 - 新增依赖前先说明必要性避免随意引入。 - 所有错误处理必须考虑失败路径不能只写happy path。 - 输出代码时附上简要说明解释核心思路而非逐行注释。 - 优先使用项目已有的模式不要自行发明新风格。这段规则帮我省了很多事。以前经常遇到AI顺手把代码格式改得乱七八糟、或者注释写得比代码还长的情况有了全局规则之后这类问题基本绝迹。你可能觉得这些规则是常识但AI并不会自动知道你的偏好明确写出来它就是你的稳定行为基线。3.3 项目级CLAUDE.md的编写示例项目级的CLAUDE.md才是真正展示这项目的地基的地方。以我维护的一个Node.js TypeScript后端服务为例# 项目OrderFlow 订单服务 ## 职责范围 处理订单创建、支付回调、库存扣减与退款流程。所有订单状态变更必须写审计日志。 ## 技术栈与目录 - 运行时Node.js 20 TypeScript 5.xESM 模块。 - 框架Fastify不使用 Express。 - 数据库PostgreSQL Prisma ORM。 - 消息队列BullMQ Redis。 - 目录结构 - src/modules/领域/ 按领域拆分每个领域包含 routes、services、repositories。 - src/lib/ 存放跨领域共享的工具函数。 - prisma/ 数据库 schema 与迁移文件。 ## 开发约束 - 所有Controller/Route层只做参数校验和响应组装业务逻辑一律在 service 层。 - Repository 层禁止写复杂联表查询复杂查询放到专门的 query 文件里。 - 订单金额以分为单位的整数存储禁止浮点数。 - 所有对外接口必须提供 requestId日志中必须包含 requestId 链路。 - 数据库变更必须同步更新 prisma/schema.prisma 与迁移文件禁止直接改线上数据库。 ## 常用命令 - 开发npm run dev自动启动 Fastify 并监听 3000 端口 - 测试npm run test使用 Vitest - 类型检查npm run typecheck - lintnpm run lintESLint Prettier这个文件写完之后Claude Code对项目的理解几乎达到了一个刚入职一周、认真读过代码库的工程师的水平。它知道该在哪一层加逻辑知道不能碰浮点数知道每次改接口要带链路追踪。这种懂规矩的状态输出的代码质量跟之前完全不在一个量级。3.4 定义自定义命令并配好参数接下来定义命令模板。我拿/review命令做例子它的文件内容大致长这样--- description: 对当前改动执行全面的代码审查输出结构化报告 argument-hint: 可选指定重点审查的模块或文件路径 --- 请对当前 Git diff 做一次完整的代码审查。审查过程中必须遵守项目 CLAUDE.md 中的约束并重点检查以下方面 1. 逻辑正确性是否存在边界条件遗漏、并发问题、状态一致性隐患。 2. 安全性是否有注入、越权、敏感数据泄露风险。 3. 性能是否存在不必要的重复查询、循环内IO、内存泄漏点。 4. 可维护性命名是否清晰、结构是否符合项目的分层规范。 5. 测试覆盖改动是否涉及需要补充测试的逻辑。 输出格式 - 按问题严重程度排序给出问题清单。 - 每个问题标注涉及的文件与行号区间。 - 给出具体修改建议优先使用项目现有模式。 {{args}}{{args}}是参数占位符用户可以在敲/review src/modules/payment时把具体路径作为参数传入。这个命令的好处是把AI自由发挥的审查变成了按固定标准流程的审查每次输出的报告结构和质量都很有保证。另一个很实用的命令是/commit--- description: 生成符合 Conventional Commits 规范的提交信息 --- 根据当前 git diff生成提交信息。要求 - type 使用 feat / fix / refactor / docs / test / chore 之一必要时加上 scope。 - 标题简洁不超过 60 个字符使用祈使句。 - body 说明改动动机和影响范围不要复述代码改动本身。 - 如果有 breaking change必须以 BREAKING CHANGE: 开头标注。3.5 配置一个Code Review SkillSkill的定义比命令更细也更专业化。我在.claude/skills/security-review/SKILL.md里写了这样一套东西--- name: security-review description: 在代码审查、安全审计、依赖检查等涉及安全性的场景下使用提供系统性安全分析方法 --- 目标是识别代码中的安全缺陷并按OWASP Top 10与CWE清单给出修复建议。 ## 审查流程 1. 输入梳理先了解代码的输入来源、信任边界和数据流。 2. 逐项排查 - 注入类SQL注入、命令注入、XSS、NoSQL注入。 - 认证与授权是否存在越权访问、水平/垂直提权路径。 - 敏感数据日志是否打印敏感字段、存储是否加密、传输是否走TLS。 - 业务逻辑验证码校验、限流、重放攻击、竞态条件。 - 供应链依赖版本是否过旧、lockfile是否有异常来源。 3. 输出报告按风险等级高/中/低输出问题清单每个问题包含 - 风险描述与攻击场景。 - 涉及的文件与代码行。 - 具体的修复代码示例优先使用项目现有依赖实现不引入不必要的库。一个Skill写得好不好关键看它的触发描述和内容质量。描述决定了什么场景会唤醒它内容质量决定了唤醒之后的输出水平。技能一旦开启Claude Code在处理安全性相关任务时的思考路径会变得非常规范不会再想到哪聊到哪。3.6 用Hooks锁住自动化流程hooks配置写在.claude/settings.json里。以下是我常用的一个配置片段作用是在AI执行读取文件修改代码的常用工作流时提醒它遵守项目规范{ hooks: { PreToolUse: [ { matcher: Read|Edit, hooks: [ { type: command, command: echo 提示修改代码前请确认目标文件属于哪个模块并遵循模块内部已有的代码风格。不要在改动中夹带与任务无关的重构。 } ] } ], PostToolUse: [ { matcher: Edit, hooks: [ { type: command, command: node .claude/scripts/check-lint.js } ] } ] } }PreToolUse在AI调用工具前触发适合做提醒和拦截PostToolUse在工具执行后触发适合做校验。你完全可以发挥创造力代码修改后自动跑lint、单元测试失败时自动阻止提交、文档更新后自动同步目录结构等等。hooks让AI的行为有了制度保障这是单纯靠提示词做不到的。4. 常见问题与排查技巧实录4.1 CLAUDE.md写了但AI有时不遵守这是最常遇到的问题。排查思路很简单先确认你加载的是不是项目级的CLAUDE.md。Claude Code在启动时会读取当前目录下的CLAUDE.md如果你在子目录里操作可能加载的是子目录的局部配置而非根目录配置。另一个容易被忽视的原因是CLAUDE.md里规则写得太长、太杂AI真正记住的是重点中的重点次要规则直接被上下文淹没。解决办法是给规则分优先级。把必须执行的规则控制在10条以内放在文件最前面后面的内容定位为参考信息。如果规则实在多可以把详细版本拆到子文件用遇到相关任务时阅读 docs/xxx.md来触发。4.2 自定义命令不生效或参数传递异常命令不生效九成是文件位置或文件名出了问题。.claude/commands/下的文件名就是命令名如果你的文件叫code-review.md终端里就要敲/code-review。另一个容易踩的坑是frontmatter写得不对比如description没写命令虽然有但提示不全。参数传递这块要注意{{args}}占位符的位置很关键。如果你在指令开头就用了参数但在提示里又说可选AI可能会因为参数为空而卡住。我的建议是把参数默认值写清楚比如如果args为空则默认审查当前分支最近5个提交。这样不论用户传不传参命令都跑得通。还有一点命令文件的描述是第一生产力描述够清楚AI在判断什么场景该用什么命令时就不会犹豫。4.3 Skill不触发或触发不准确Skill的触发完全靠文件里的description字段。如果description写得太笼统比如用于代码审查那它几乎不会自动激活因为AI觉得普通对话上下文已经够用了。要让Skill精准触发description要尽量贴近真实任务的表述把触发场景和关键词写清楚。另外一个很实用的技巧是给Skill的description里加上触发条件和使用范围的说明。比如上面那个security-review的例子描述中明确包含安全审计、依赖检查等涉及安全性的场景这样当对话涉及安全话题时Skill被激活的概率会大幅提升。4.4 上下文窗口不够用CLAUDE.md、命令模板、Skill文件一次加载太多会挤占上下文窗口。如果你发现AI的记忆越来越差甚至忽略你最近说的高优先级指令那大概率是模板内容太肥了。我的习惯做法是定期清理CLAUDE.md只留核心规则长篇的代码风格指南迁移到Skill里按需加载命令模板保持流程导向不要写成教科书Settings里的hooks脚本只输出关键信息。另外项目模块越来越多之后可以考虑把目录说明拆到模块级CLAUDE.md里这样AI在某个模块内工作时只需要加载该模块的局部上下文全局窗口的压力会小很多。5. 把这套模板体系推向团队协作如果你是一个人在用这套模板那以上内容已经足够。但如果你在团队里工作模板的价值还能再放大一截。团队协作时项目级的CLAUDE.md和命令模板应该作为团队资产来维护。可以指定一个人负责维护或者通过Pull Request的方式让大家共同参与更新。尤其要注意的是当团队技术选型发生变化比如引入了新的状态管理库、调整了目录规范一定要同步更新CLAUDE.md否则AI还在按旧规则干活会耽误整个团队。我见过一个团队把CLAUDE.md当成活的文档来管理每半周根据AI最近犯过的错误更新一次规则。比如有几次AI总是把接口响应的数据结构搞混他们就在CLAUDE.md里追加了一条明确的约束。这个习惯带来的变化非常明显AI的犯错率一周比一周低输出的代码越来越接近团队的人味。这套模板体系其实一直在演进。Claude Code本身迭代很快新的配置项、新的技能格式随时可能出来。我的建议是别等到版本全稳定了再动手先用现有的机制把你的项目规则固定下来等新特性出了再迁移成本远比你想象的低。我自己就是从一张薄薄的CLAUDE.md开始一路滚到现在这套涉及命令、技能、钩子的完整配置整个过程几乎是无痛的。最后分享一个小技巧每次让AI做出你特别满意的输出时回头去看看是不是有某条规则起了作用。如果是把那条规则在模板里加粗或者往前调每次遇到它表现不佳的场合也去模板里找找有没有对应的盲区。这套模板不是一次写完的它是你和AI协作习惯的持续沉淀。养好这份档案你的Claude Code会越来越像一个真正在项目里干了很久的搭档。