Claude Code模板体系搭建：从CLAUDE.md到Hooks与子代理实战

Claude Code模板体系搭建：从CLAUDE.md到Hooks与子代理实战

发布时间：2026/10/17 5:24:29
Claude Code模板体系搭建：从CLAUDE.md到Hooks与子代理实战 带着一套模板进 Claude Code和裸奔完全是两个体验。我用了大半年踩了不少坑才总结出这套东西——从一份 CLAUDE.md 到完整的命令、钩子、子代理配置全部可以塞进项目仓库或者直接同步到全局配置。这篇主要讲清楚模板体系怎么搭、每部分到底管什么、实际项目里怎么用以及我踩过的坑。想直接抄作业的照着第四节的示例复制改改就行。1. Claude Code 模板到底在解决什么问题先说个场景。你开了个新项目让 Claude Code 帮你改代码结果它既不认识你们项目的目录结构也不清楚用哪个包管理器更不知道代码规范是分号派还是无分号派。每换一个项目都要重新交代一遍背景遇到复杂的仓库光解释上下文就能耗掉十几分钟。更麻烦的是团队协作。你调好的规则、写好的命令、固定的提交流程别人根本不知道你配过这些。新成员用同一个工具跑出来的行为完全不一样。模板要解决的核心就三个词一致性、复用性、可控性。所谓模板在 Claude Code 语境下并不是一个单文件而是一整套配置的集合。主要包括CLAUDE.md项目的长期记忆告诉模型这个项目是什么、怎么跑、有什么约定。.claude/commands/自定义斜杠命令把高频操作封装成一句/review或/commit。.claude/settings.json环境级配置比如权限、钩子、模型参数。.claude/agents/子代理定义把某个专业角色代码审查、测试编写、文档维护固化成模板。Hooks在关键节点触发自动化脚本比如禁止在特定目录执行危险命令。把这五样组合起来你就会得到一个行为稳定的 AI 编程搭档。换项目、换电脑、换同事拉下仓库跑一次初始化所有规则自动生效。这也是我为什么强烈建议模板入库而不是只放在个人目录——配置跟着项目走大家用的才是同一个版本。2. 五个核心组件逐一拆解2.1 CLAUDE.md项目的人肉说明书CLAUDE.md是整个模板体系的地基。它的本质是给模型一份常驻上下文不用每次对话都重复交代背景。默认情况下Claude Code 会自动读取项目根目录下的CLAUDE.md子目录也可以有自己的CLAUDE.md模型进入对应目录时会额外加载。我见过不少人把 CLAUDE.md 写成一本流水账项目简介、技术栈、目录结构、历史变更全堆进去。这是错的。模型上下文窗口再大也经不起你这么浪费。好的 CLAUDE.md 只回答一个问题如果我是刚入职的工程师打开这个仓库第一件事想知道什么给你看一份我实际在用的简化版# Project: order-service ## 技术栈 - Node.js 20 TypeScript 5.x Fastify - 数据库PostgreSQL 16ORM 使用 Prisma - 队列BullMQ Redis - 包管理pnpm不要用 npm ## 常用命令 - pnpm dev本地开发监听 3000 端口 - pnpm test跑单测注意需要本地 Redis - pnpm db:migrate执行数据库迁移 ## 架构约定 - 业务代码在 src/modules/模块名/ 下包含 controller、service、repository 三层 - 所有对外 API 必须走 controller禁止在 service 里直接返回 HTTP 响应 - 错误统一使用 AppError 类code 字段遵循 ERROR_前缀规范 ## 编码规范 - 使用 Biome 做 lint配置在 biome.json不要引入 ESLint - 提交信息遵循 Conventional Commits - 类型定义放在 src/types/ 目录禁止在业务代码里写 any注意我写的内容顺序技术栈决定命令架构约定决定代码怎么落地编码规范决定审查标准。没有废话每条都能直接指导行为。这里有个技巧每次 Claude Code 做错事你就把对应规则补进 CLAUDE.md 里。比如它老是在你某个目录里乱写测试文件你就在规范里加一条测试文件必须与源码同名放在tests目录。一个月下来你的 CLAUDE.md 就是最贴合自己工作流的行为准则。2.2 自定义 Slash Commands把高频操作变成一句话Slash Command 是 Claude Code 的快捷指令存放在.claude/commands/目录下每个文件是一个 Markdown比如.claude/commands/review.md。你输入/review时模型会读取这个文件的内容作为提示词执行。命令文件的写法很有意思。你可以把它理解为一段固定的指令模板 运行时参数。最简单的命令--- description: 审查当前工作区的改动 --- 请审查当前 git diff 中的所有改动重点关注 1. 是否存在潜在的并发问题 2. 错误处理是否完整 3. 是否有破坏现有测试的改动 输出格式 - 高风险问题注明文件、行号、原因 - 建议改进按优先级排序 - 可以直接执行的修复命令description字段会在命令菜单里显示。文件名就是命令名所以命名要短、要能猜到意思。我常用的几个review审查、commit生成规范化提交信息、test为当前改动补测试、explain逐段解释某段代码、refactor执行一次小重构。命令文件里还可以写$ARGUMENTS占位符把用户输入的内容插进来。比如请先解释这段代码的作用然后按照项目重构约定给出修改建议。涉及文件$ARGUMENTS这样一来/explain src/service/order.ts就能针对目标文件干活。命令文件永远是 Markdown但你可以从简单提示词一直写到几十行的复杂工作流区别只在于你愿意封装多少细节进去。2.3 Hooks 与自动化在关键时刻设置刹车Hooks 是 Claude Code 里容易被人忽略却极其有用的功能。它允许你在工具调用前、后、以及对话进程中挂载脚本对行为进行拦截或增强。说白了它给 AI 的自由度装上了护栏。配置写在.claude/settings.json里常见的钩子事件有PreToolUse工具执行前触发可以用来阻止危险操作PostToolUse工具执行后触发可以做校验、汇总UserPromptSubmit用户提交消息时触发可以做关键词替换或附加上下文Stop一轮对话结束时触发用于执行收尾动作Notification需要人工介入时触发通知我给一个真实例子。团队有人习惯在代码里console.log调试提交前老忘记清。我在PostToolUse挂了一个脚本每次写完文件后自动扫描新增的console.log并警告要求用logger.info替换。脚本用 Node 写的挂在.claude/hooks/check-console-log.mjs// .claude/hooks/check-console-log.mjs export async function postToolUse({ tool_name, tool_input, tool_response }) { if (tool_name ! Write tool_name ! Edit) return {}; const files tool_input.file_path ? [tool_input.file_path] : []; const hits []; for (const file of files) { const content require(fs).readFileSync(file, utf8); if (/console\.(log|debug)\(/.test(content)) { hits.push(file); } } if (hits.length 0) { return { hookSpecificOutput: { hookEventName: PostToolUse, affectedItems: hits, shouldStop: false, message: 检测到 ${hits.join(, )} 中存在 console.log请改用 logger.info, }, }; } return {}; }注意这里shouldStop设为false意思是只警告不阻断。如果你希望模型必须修复后才能继续可以结合PreToolUse来实现更强的约束。Hooks 的返回结构有点绕我一开始也经常漏hookSpecificOutput字段导致提示不生效。这个下面第五节再展开讲。2.4 Agents / Subagents给不同任务分配专职角色Claude Code 的 Agent 体系允许你定义子代理每个子代理有独立的系统提示词由主对话按需调用。模板放在.claude/agents/目录每个文件对应一个角色。举个例子。我定义了一个叫code-reviewer的子代理--- name: code-reviewer description: 资深代码审查员专注发现边界条件、并发安全和性能问题 tools: Read, Grep, Glob --- 你是一名有 10 年经验的资深代码审查员。你的职责是 - 只关注正确性和潜在缺陷不讨论格式问题 - 对每个问题标注严重级别Critical / Major / Minor - 必须给出具体的复现场景或触发条件 - 提出修复建议时必须基于项目现有代码风格使用方式是在对话里让主模型调用 code-reviewer 审查 src/order/service.ts。主模型会根据任务描述和你定义的 description 判断该用哪个子代理然后把对应代码信息传给它去执行。子代理的价值在于隔离上下文和职责。主对话上下文太大时让子代理独立处理子任务能有效降低主上下文被无关信息污染的概率。而且不同子代理的tools字段可以做权限隔离——比如某个只读审查角色就只给它Read, Grep, Glob三个工具不给写权限。2.5 全局配置与多层级覆盖模板不是只能放在项目里。全局的~/.claude/CLAUDE.md可以放适用于所有项目的通用规则比如不要修改锁文件、先阅读现有测试再动手项目的CLAUDE.md自然覆盖全局子目录的CLAUDE.md再覆盖项目级。这跟 CSS 的层叠规则很像。我建议的分层原则是全局层~/.claude/跨项目的工作习惯、代码风格底线、安全红线项目层根目录.claude/技术栈、架构约定、提交流程、团队规范目录层子目录 CLAUDE.md特定模块的局部细节尽量少用还有一个CLAUDE.local.md它不会被提交到 git属于个人私有记忆。比如这个项目的 owner 是某某找他确认需求这类临时信息。我通常用它记一些跟团队成员协作时的口头约定不会污染公共模板。3. 搭建模板体系从零到能用的四步3.1 先做减法确定模板边界搭模板之前先回答三个问题常做什么类型的项目哪些操作重复出现哪些错误反复踩坑这三个答案直接决定你的模板内容边界。如果你是接外包的全栈开发可能只需要通用一点的全局模板 每个项目一份简短 CLAUDE.md如果你是某个复杂系统的长期维护者那项目模板必须深入甚至要配好几个子代理和 hooks。别一上来就搞大而全的模板全家桶我从头到尾配过一轮,后面删掉的东西比留下的多。3.2 初始化目录结构与基础文件Claude Code 模板的标准骨架长这样your-project/ ├── CLAUDE.md ├── CLAUDE.local.md # 可选不提交 git └── .claude/ ├── settings.json ├── commands/ │ ├── review.md │ ├── commit.md │ └── test.md ├── agents/ │ └── code-reviewer.md └── hooks/ └── check-console-log.mjs你也可以在~/.claude/下平行建一套全局版本。先手动建目录然后从最小核心开始一份根目录的CLAUDE.md加一个/review命令。跑通了再加 hooks最后补 agents每加一个组件都验证一次效果。3.3 把规则写进去用真实任务检验很多人的模板是写出来的不是长出来的。我建议的方法相反别提前写一堆规则先在默认配置下干活每次发现模型行为不符合预期就把规则补进去。比如你发现 Claude Code 每次改代码都顺手把 import 排序弄乱你就补一条不要改动未提及文件的 import 语句发现它总是自作主张把 pnpm 换成 npm你就补一条包管理器固定为 pnpm。用这种方式积累两周你的模板会非常贴合实际需求而不是一堆正确的废话。3.4 团队协作与模板同步模板入库之后团队协作就顺了。但有个坑CLAUDE.md 的变更不会自动通知模型。模型每次启动时读一次如果你的仓库是 clone 之后很久没更新本地模板可能已经过期。解决方法是把更新模板后重启会话写成流程规范或者在命令里做一个/refresh命令触发一次模板重读。严格来说 Claude Code 没有热重载命令但你可以通过重启对话来强制刷新习惯养成后问题不大。4. 实战一套后端项目模板的完整参考下面给你一份可以直接改用的完整配置基于一个常见的 Node.js TypeScript 后端仓库。4.1 CLAUDE.md上下文与项目地图# Project: payment-gateway ## 项目定位 支付网关服务负责交易路由、对账、回调通知。仓库为 monorepo 核心代码在 apps/api 中。 ## 技术栈 - Node.js 22 TypeScript 5.6 Fastify - PostgreSQL 16 Prisma ORM - Kafka 用于异步事件 - pnpm workspace 管理依赖禁止使用 npm/yarn ## 快速开始 - pnpm install - cp .env.example .env - pnpm db:up # 启动本地数据库 - pnpm dev # 开发模式端口 8080 ## 目录结构 - apps/api主服务入口 - packages/domain领域模型禁止依赖基础设施 - packages/infra数据库、消息队列等基础设施封装 - apps/worker消费异步任务的 worker 进程 ## 架构约定 - 每个功能模块按模块化组织模块间通过接口通信禁止跨模块直接 import 内部实现 - 领域层不依赖 Prisma通过 Repository 接口访问数据 - 回调处理必须做幂等幂等键为 orderId eventType - 所有金额计算用 integer分禁止浮点数 ## 代码规范 - Biome 负责 lint 和 format配置见 biome.json - 提交信息遵循 Conventional Commits - 任何对外接口改动必须先更新 OpenAPI 文档 - 新依赖必须经过架构评审禁止引入未经确认的包4.2 命令把审查、提交、补测做成一条命令.claude/commands/review.md--- description: 审查当前分支改动输出问题清单 --- 审查当前 git diff 相对 main 分支的全部改动。 审查维度按优先级排序 1. 资金安全金额计算、幂等、并发扣款是否有竞态 2. 数据一致性事务边界、缓存失效、回滚补偿是否缺失 3. 接口兼容是否破坏现有回调方对接 4. 错误处理异常路径是否有兜底 禁止审查格式和命名这类风格问题交给 lint。 输出时每个问题必须注明文件、行号、严重级别Critical/Major/Minor和修复建议。.claude/commands/commit.md--- description: 生成符合 Conventional Commits 的提交信息 --- 根据当前 git diff 生成提交信息。 要求 - 遵循 Conventional Commits 格式type(scope): subject - type 可选值feat / fix / refactor / docs / test / chore / perf - subject 不超过 72 个字符用祈使语句 - 如果改动涉及多个模块在 body 里列出每个模块的变更点 确认信息后由我手动执行 git commit不要直接执行。4.3 Hooks提交前防线和状态检查.claude/settings.json{ permissions: { allow: [ Read, Glob, Grep, Write, Edit, Bash(pnpm *) ], deny: [ Bash(git push*), Bash(rm -rf *), Bash(pnpm publish*) ] }, hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: node .claude/hooks/check-console-log.mjs } ] } ], PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: node .claude/hooks/block-dangerous-command.mjs } ] } ] } }.claude/hooks/block-dangerous-command.mjsexport async function preToolUse({ tool_name, tool_input }) { if (tool_name ! Bash) return {}; const cmd tool_input.command || ; const blockedPatterns [ /git\spush/, /git\sreset\s--hard/, /rm\s-rf/, /drop\stable/i, /pnpm\spublish/, ]; const hit blockedPatterns.find((pattern) pattern.test(cmd)); if (hit) { return { hookSpecificOutput: { hookEventName: PreToolUse, shouldStop: true, message: 命令 ${cmd} 被模板安全策略拦截。如需执行请手动在终端操作。, }, }; } return {}; }这份配置是我真实在用的简化版。你可以看到 hooks 承担了人不一定每次盯着、但 AI 也不能乱来的兜底作用。配合permissions的白名单/黑名单基本的操作安全就有了。4.4 子代理代码审查与测试生成分工.claude/agents/test-writer.md--- name: test-writer description: 专门编写单元测试覆盖率优先只负责测试文件 tools: Read, Glob, Grep, Write, Edit --- 你是一名测试工程师。根据用户指定的源代码模块编写单元测试 - 测试框架使用 Vitest测试文件放在 src/**/__tests__/ 目录 - 每个测试必须覆盖正常路径、边界值、异常路径 - 禁止 mock 掉被测函数所在的模块内部逻辑 - 测试命名使用 描述性中文或英文均可但必须能看出场景 写完测试后自行执行 pnpm test -- 目标文件 验证失败则修复直到通过。这个子代理很方便的原因在于它可以自己读源码、自己写测试、自己跑测试验证而不需要主对话来回切换上下文。只需要在对话里说一句让 test-writer 给 order.service.ts 补测试就行。5. 常见问题与排查记录使用模板体系过程中我遇到的问题不少挑典型的整理成一个速查表问题现象原因解决办法改了 CLAUDE.md 但模型行为没变化会话启动时加载的旧模板未重启重启对话或新开会话验证自定义命令/xxx无法唤起文件不在.claude/commands/或文件名后缀问题确认路径正确文件名必须是.md且不含空格Hook 脚本报了exports is not defined使用了 CommonJS 语法但 Claude Code 按 ESM 加载检查package.json的type字段统一用 ESM 的export写法Hook 返回了对象但模型不看提示缺少hookSpecificOutput包装返回结构必须严格用{ hookSpecificOutput: { hookEventName, shouldStop, message } }Hooks 命令脚本要用jq处理 JSON环境没装改用 Node 脚本跨团队时避免依赖未统一的命令行工具子代理没有按预期调用description写得太泛模型判断不了把 description 写明确比如处理单元测试相关任务而不是测试权限黑名单不生效settings.json 的 permissions 结构层级写错确认permissions.deny是数组匹配规则按文档写其中一个特别值得单独说的是 hooks 的 JSON 解析问题。钩子脚本通过 stdin 接收 JSON 事件返回内容也必须是通过 stdout 输出的 JSON。我早期写脚本时总在脚本里输出一些调试日志结果 Claude Code 把日志当成返回结果解析直接报错。排查了很久才发现是 stdout 污染。之后我所有的 hook 脚本都统一规则stdout 只输出最终 JSON调试信息写到 stderr 或日志文件。另外提醒一句权限配置别一刀切。我见过有人把Write直接禁了结果是模型干活时频繁卡在权限确认上体验极差。正确做法是允许高频且安全的工具只对 Bash 类命令做精细的正则匹配。宁可多触发一次确认也别把模型的手脚捆死。最后一点实际体会我个人的习惯是把模板当成项目文档的一部分来维护而不是配完就算完。每次对模型行为不满意第一反应不是重新描述一遍需求而是是不是模板里缺少了一条规则。这个思维转换之后模板就成了一个越用越准的资产。另外提醒一下.claude/目录如果涉及团队规范建议提交到仓库并加进 Code Review 范围避免团队里有人悄悄改掉公共配置。你要是刚接触这套体系先从一份 CLAUDE.md 和一个/review命令开始跑两周再往里加东西比我一开始就堆满所有组件要从容得多。