我是在一个周四下午决定认真折腾claude-code的 templates 体系的。起因很朴素连续三个项目每次新建会话都要重新跟 AI 解释一遍我们的技术栈是什么、错误处理怎么约定、哪些目录不能乱动。本来以为多打几句提示词就行结果发现 Claude Code 的上下文窗口就像人的短期记忆换个会话就清零。真正让我下决心搞模板化的是一次代码审查——AI 在完全不知道项目规范的情况下给一个 Python 项目提出了建议引入 lombok这种离谱意见。这篇内容围绕claude-code和templates展开想跟你聊聊我怎么把 Claude Code 的上下文、角色、任务流程全部沉淀成一套可复用的模板体系让 AI 在开新会话、新项目、甚至团队成员手里都能保持一致的职业素养。如果你是那种已经用过 Claude Code、但对每次重复调教感到疲惫的开发者或者你想把团队的 AI 协作方式规范起来这篇文章应该能给你一份可以直接上手的参考。1. 为什么必须给 Claude Code 上模板我的项目失忆惨案在聊模板怎么写之前我觉得有必要先讲清楚为什么要模板。因为我见过太多人把 CLAUDE.md 当成摆设或者把所有希望都寄托在每次对话时多说几句上。这两种做法本质上都没有解决一个核心问题AI 在每一次会话里都是一个有知识但没记忆的新人。1.1 从无效对话到模板化的转变节点我的项目失忆惨案发生在接手一个前端 monorepo 的时候。项目里有五个 workspace 包每个包的构建工具、测试框架、代码风格都不一样。我在第一个会话里花了大半个小时跟 Claude Code 讲解项目结构AI 也顺利帮我改了第一个包的代码。但第二天我重新打开终端新会话里的 Claude 完全不记得那些约定——它把一个只在 workspace A 里存在的依赖直接 import 进了 workspace C构建直接崩了。那一刻我意识到对话式编程最大的成本不是推理是上下文对齐。每次开新会话AI 都要重新认识这个项目。如果你不把这些信息固化下来等于每天都在让一个聪明的新人从零开始熟悉工作环境。1.2 模板要解决的三类问题上下文、角色、流程想清楚之后我把需求拆成了三类问题类型典型场景对应机制上下文缺失AI 不知道项目技术栈、目录规范、常见陷阱CLAUDE.md 项目记忆文件角色混乱AI 在写代码时顺便越权做审查、乱改无关文件Subagent / Agent 角色模板流程不固定每次代码审查的标准不一、重构步骤随意/command 命令模板 Hooks简单说templates不只是文件模板而是一整套让 AI 行为可预期的基础设施。CLAUDE.md 解决AI 知不知道的问题Agent 模板解决AI 是什么角色的问题命令模板和 Hooks 解决AI 按什么流程干活的问题。三者叠起来才是完整的模板体系。2. 模板体系的分层设计从全局到项目的三级结构设计模板体系的第一步不是写模板内容而是确定目录结构和加载规则。我见过有人把所有的约定全塞进项目的 CLAUDE.md结果文件越来越长AI 抓不住重点。也有人什么都不分层全局文件和项目文件互相打架。这两种都属于有模板但没体系。2.1 目录结构设计我最终落地的目录结构是这样的~/.claude/ ├── CLAUDE.md # 全局记忆所有项目通用的协作约定 ├── commands/ # 全局命令模板如 /code-review │ ├── code-review.md │ ├── test-writer.md │ └── refactor-step.md ├── agents/ # 全局角色模板 │ ├── code-reviewer.md │ ├── security-auditor.md │ └── api-designer.md └── hooks/ # 自动检查脚本 ├── pre-tool-use.ts └── post-tool-use.ts 你的项目目录/ ├── CLAUDE.md # 项目级记忆覆盖项目专属约定 └── .claude/ ├── settings.json # 项目级配置 ├── commands/ # 项目专属命令 ├── agents/ # 项目专属角色 └── hooks/ # 项目专属检查这套布局的核心逻辑是全局目录管通用能力项目目录管专属差异。比如所有项目都该遵守的 git 提交规范、代码审查的基本维度放全局而某个项目特有的 API 错误码格式、数据库访问约定放项目里。这样你换新项目时全局模板自动生效只需要补充项目专属的那层。2.2 每个层级的加载规则Claude Code 在启动时会自动读取全局~/.claude/CLAUDE.md和当前项目的CLAUDE.md按顺序合并作为对话背景。命令模板和 Agent 模板通过文件名调用Hooks 则在工具调用的事件节点触发。我建议你把下面这张加载优先级表贴在某处防止自己写着写着就忘了配置项全局来源项目来源加载优先级CLAUDE.md~/.claude/CLAUDE.md./CLAUDE.md项目优先合并加载commands~/.claude/commands/./.claude/commands/同名时项目覆盖全局agents~/.claude/agents/./.claude/agents/同名时项目覆盖全局settings~/.claude/settings.json./.claude/settings.json项目优先对象级合并hooks~/.claude/hooks/./.claude/hooks/两端都会执行这套规则理解起来不复杂命令和角色用就近覆盖上下文用叠加融合Hooks 用全都生效。唯一要注意的是 CLAUDE.md 的合并方式——全局和项目是拼接的所以全局文件里不要写这个项目如何如何这种专属描述否则每个项目都会读到不属于自己的约定。3. CLAUDE.md 模板给 AI 一本不会过时的项目手册CLAUDE.md 是整个模板体系的地基。它相当于你在入职第一天发给新同事的项目手册里面写清楚我们做什么、怎么做事、有哪些坑。我强烈建议每个项目都维护一个 CLAUDE.md而且把它当成像 README 一样重要的文件。3.1 CLAUDE.md 的核心字段我自己的 CLAUDE.md 模板会固定包含这些字段项目一句话定位让 AI 在最短时间内理解项目边界。技术栈清单语言、框架、核心库、包管理器精确到版本。目录结构速览不用全列列出关键模块和它们的职责。编码约定错误处理、命名规范、分层规则、禁止事项。常用命令启动、测试、构建、lint 的确切命令。已知陷阱历史踩过的坑、容易误改的区域、性能雷区。这里要特别提醒CLAUDE.md 不是写给 AI 看的作文素材而是写给 AI 的决策依据。字段太多太全反而会稀释重点。经验法则——控制在 80 到 120 行以内只保留那些不知道就会写错的信息。3.2 一个可以直接抄的 CLAUDE.md 模板这是我最近一个 Python 后端项目的 CLAUDE.md 缩略版# order-service ## 一句话定位 电商订单核心服务负责下单、支付回调、订单状态流转。 ## 技术栈 - Python 3.12 FastAPI - PostgreSQL 15 SQLAlchemy 2.0 - Redis 7缓存与分布式锁 - 包管理: poetry ## 目录结构 - app/api/HTTP 路由层只做参数校验和响应封装 - app/service/业务逻辑层所有事务边界在此层 - app/repository/数据访问层禁止向上层暴露 SQLAlchemy Session - tests/pytest 测试按模块镜像 app 结构 ## 编码约定 - 错误处理统一抛 AppError(code, message)禁止裸 raise Exception - 所有数据库写操作必须在 service 层开启事务 - 接口响应统一使用 ApiResponse 包装禁止直接返回 dict - 新模块必须附带对应单元测试 ## 常用命令 - 启动: poetry run python -m app.main - 测试: poetry run pytest - lint: poetry run ruff check . ## 已知陷阱 - Redis 缓存序列化使用项目自定义 JSONEncoder不要直接 json.dumps - 支付回调接口必须校验签名测试时使用 tests/fixtures 里的样例数据 - order_status 字段流转只能按状态机顺序禁止跳过中间状态这个模板加上去之后Claude Code 新会话里写出来的代码基本能直接通过 CI 审查。原因很简单AI 在生成第一行代码之前就已经知道这个项目的游戏规则了。它不会再问你们用什么数据库这种基础问题也不会写出风格突兀的代码。4. 角色模板把 AI 固定成你团队里的专职工程师CLAUDE.md 解决的是AI 知道什么但AI 以什么身份、什么态度干活是另一件事。我见过太多人让 Claude Code 在写代码的同时顺便做代码审查结果它一边改一边夸自己审查意见全是在给自圆其说。这就是典型的角色混乱——让一个写代码的人同时当裁判裁判很难做到客观。4.1 Subagent 的运作机制与适用场景Claude Code 支持 Subagent也就是子代理。你可以在配置里定义多个专职 Agent比如代码审查员、安全审计员、测试生成员。主对话可以按需把任务委派给对应的 Agent然后汇总结果。每个 Agent 有自己独立的提示词、工具权限和专注目标不会跟主对话抢活干。注意我前面表格里提到的tools字段这是角色模板里最关键的配置。你在定义 Agent 时应该明确它能用哪些工具比如审查员可以读文件、搜代码、跑测试但不能写文件。这样就从工具层面强制隔离了说和做的权限AI 再想越权也没办法。4.2 一个审查 Agent 模板示例下面是我在~/.claude/agents/code-reviewer.md里用的模板--- name: code-reviewer description: 对代码变更进行严格审查输出分级审查意见不修改任何文件 tools: Read, Grep, Glob, Bash --- 你是一名资深代码审查工程师你的职责是客观、严格地审查代码变更。 ## 审查步骤 1. 先用 Read 和 Grep 定位本次变更涉及的文件与函数 2. 对照项目 CLAUDE.md 中的编码约定逐条检查 3. 重点审查错误处理路径、资源释放、并发安全、敏感数据泄露 4. 运行相关测试确认变更没有破坏现有功能 ## 输出格式 按以下三级分类输出意见 - [必须修改] 会导致线上故障或安全隐患的问题 - [建议修改] 不符合项目规范或影响可维护性的问题 - [非阻塞建议] 风格优化或潜在改进点 ## 禁止行为 - 禁止直接修改任何文件 - 禁止提出与项目 CLAUDE.md 冲突的建议 - 禁止使用可能也许等含糊措辞每个问题必须给出具体文件与行号加了tools限制之后审查 Agent 只能看和查不能改。这让整个审查流程变得非常干净主对话把变更区域交给它它输出意见人类决定改什么。团队成员也可以共用同一个 Agent 模板保证审查标准在所有项目里完全一致。5. 任务模板把代码审查和重构变成一条命令模板体系里最实用、见效最快的其实是命令模板。Claude Code 支持自定义/commands你写一个 Markdown 文件里面放一段精心设计的提示词之后在对话里输入/code-review就能触发。这相当于给 AI 预置了一套工作 SOP。5.1 命令模板的语法与调用方式命令模板文件放在commands/目录下文件名就是命令名比如code-review.md对应/code-review。文件支持 frontmatter 和正文两部分。frontmatter 可以声明命令的描述、参数提示正文是核心告诉 AI 拿到这个命令后该按什么流程执行。一个我常用的格式骨架是--- description: 对当前工作区最近的代码变更进行审查 argument-hint: [optional: 文件或目录路径] --- 你在执行代码审查任务。当前会话的工作区是项目根目录。 1. 先用 git diff HEAD~1 获取最近一次提交的变更或检查用户指定的文件 2. 逐文件分析变更对照 CLAUDE.md 检查是否符合规范 3. 输出分级审查意见必须给出具体行号 4. 不要修改任何文件只输出意见调用时直接输入/code-reviewAI 就会按照你写好的流程执行。因为命令模板把流程步骤固化下来了不管谁来触发、哪个项目触发AI 的做事顺序都是稳定的。这对团队协作尤其有价值——新人拿到项目后不用背流程敲一条命令就行。5.2 我日常用的三个命令模板除了代码审查我日常依赖的命令还有这么几个/test-writer让我先描述一个新函数的行为它自动生成覆盖正常路径、异常路径、边界条件的单元测试。它的 prompt 里我会强制要求测试必须使用项目已有的测试框架和 fixture 风格禁止引入新依赖。/refactor-step分步重构。它的核心指令是每次只重构一个函数输出重构目标、改动 diff、验证命令等待用户确认后再继续下一步。这能有效防止 AI 一次改动太大出错了都不知道在哪。/ci-debug把 CI 日志粘贴进来AI 按照定位错误类型→检查日志上下文→复现命令→给出修复建议的顺序排查。模板里会明确要求不要随机猜测每一步都要有日志依据。每个命令模板本质上都是把你自己最擅长的做事顺序编码成了一份可重复执行的提示词。命令模板写得越具体AI 的自由发挥空间就越小结果就越可控。我见过很多人抱怨AI 写测试太随意其实多半是因为你没给它定义怎么写测试的流程。6. Hooks 模板把安全检查和自动流程写进配置文件如果说命令模板是软性流程那 Hooks 就是硬性护栏。Claude Code 的 Hooks 允许你在 AI 调用工具前后自动执行脚本比如拦截危险命令、检查生成的文件名是否合法、在每次对话开始时自动加载额外上下文。这是模板体系里最容易被人忽略、但最能兜底的部分。6.1 Hook 的触发时机Hooks 的触发时机主要有几类时机触发场景典型用途PreToolUseAI 调用任何工具之前拦截危险命令、检查文件路径PostToolUse工具执行完之后自动运行 lint、收集执行结果UserPromptSubmit用户发送新消息时注入额外的上下文或规则Stop一轮对话结束时生成摘要、归档变更记录我一般会在 PreToolUse 放安全拦截类规则在 PostToolUse 放验证类规则。比如我自己在多个项目里加了禁止对git push --force放行的拦截因为真实环境里手滑的力量远超你想象。6.2 一个防护 Hook 的完整示例下面是我在hooks/pre-tool-use.ts里写的一段防护逻辑interface PreToolUseInput { toolName: string; input: { command?: string }; } export async function preToolUse({ toolName, input }: PreToolUseInput) { if (toolName Bash input.command) { // 拦截强制推送 if (/git\spush\s.*(--force|-f)/.test(input.command)) { return { stopReason: 禁止执行 git push --force如需强制推送请人工确认, }; } // 拦截直接操作生产环境的命令 if (/kubectl\s.*--context\sprod/.test(input.command)) { return { stopReason: 检测到生产环境操作命令请在人工确认后手动执行, }; } } return { stopReason: null }; }这种 Hook 本质上不是教 AI 怎么做更好而是圈定 AI 不能碰什么。因为提示词属于软约束——AI 在长对话里可能忘记某条规则但 Hook 是每次调用工具都执行的代码不受上下文衰减影响。我最开始在项目里配置这类 Hook 时团队里还有人觉得多此一举直到有人差点让 AI 跑出一条改生产库的命令Hook 直接拦下来才没人质疑了。写 Hooks 有两个要注意的细节。第一脚本本身要写得非常保守只做匹配、判断、返回不要在里面发起网络请求或执行复杂逻辑否则每次工具调用都会拖慢节奏。第二Hook 报错时默认会阻塞 AI 的下一步操作所以脚本一旦写错AI 就卡死了。我的建议是先写一个只打日志的版本跑一阵子确认没有误报再收严。7. 模板落地的起步清单与避坑记录最后这部分我想聊点落地的实操经验和踩坑记录。我见过太多人看到这里就热血沸腾把全局、项目、命令、Agent、Hooks 全配了一遍结果第二天就被各种冲突整崩溃。模板体系跟代码一样需要一个渐进式的建设过程。7.1 我可以直接照抄的起步清单如果你现在要从零开始我建议你按这个顺序来每一步稳了再加下一步写好全局~/.claude/CLAUDE.md内容只包含你所有项目通用的协作约定git 提交规范、代码审查维度、默认技术偏好。给当前最重要的项目写一份精简的CLAUDE.md控制在一屏以内。加一个/code-review命令模板马上用一次看看流程是否顺手。加一个 Subagent 模板比如 code-reviewer在代码审查场景里试着委派给它。最后再上 Hooks先只加拦截危险命令这一条硬规则。这个顺序的逻辑是先解决AI 知不知道成本最低、收益最大再解决AI 按什么流程做中等成本最后解决AI 绝不能做什么需要谨慎配置。7.2 我踩过的几个坑坑一CLAUDE.md 越写越长。我最早有一版全局 CLAUDE.md 写了三百多行结果 AI 在关键决策时反而不引用里面的信息了。后来我砍到只有六七十行只留下高频、强约束的约定效果立刻好了很多。坑二命令模板里堆砌了太多请建议之类的礼貌词。提示词的有效性不在于客气而在于明确。去掉所有客套话改成必须禁止按以下顺序执行之后AI 的遵守率明显提高。坑三Hooks 脚本没做灰度直接全量上。我第一次在项目里配 PreToolUse 时因为正则写得太宽把git push后面跟的参数误判成--force导致 AI 每次正常推送都被拦截。后来我加了一条旁路日志确认规则可靠之后才开启拦截。坑四Agent 模板的工具权限给得太宽。最初我的 code-reviewer 配了Write和Edit工具它审查完居然顺手把代码改了还跟我说我帮你优化了一处。自从把工具权限收窄到Read, Grep, Glob, Bash之后这个越权行为就再也没出现过。最后再分享一个习惯我把这套模板本身也当代码维护用 git 管理每次改动都走提交流程。这样万一哪次改动出了问题我能快速回滚到上一版。对这种决定了 AI 每一次输出质量的底层设施最好的态度就是像对待生产环境一样谨慎。