Claude Code 模板化实战：用上下文工程固化团队 AI 协作规范

过去两个月我把手头几个长期在用的 Claude Code 项目都过了一遍做了一个之前一直拖着没做的事把所有反复粘贴的提示词、每次都要重新交代的代码规范和评审清单统一收敛成了一套 claude-code-templates。搞完之后我才明确意识到一件事——在不换模型、不改参数的前提下模板化改造对产出质量的提升比我想象中大得多。这篇文章就是那套模板从设计、搭建到真实落地踩坑的完整记录适合正在用 Claude Code 写业务代码、做重构或者维护老项目的工程师也适合想给团队搭 AI 协作规范的 Tech Lead 参考。先说一个基本判断模板不是提示词集锦不是把网上抄来的 prompt 塞进一个文件夹就完事。模板的本质是上下文资产的固化。它把你希望 AI 在开始干活前必须知道的事情沉淀成一套可复用、可版本管理、可团队共享的机制。理解了这一点你才不会把模板做成摆设。1. 为什么要折腾模板从零启动和带模板启动的差距1.1 没有模板时的真实工作流长什么样很多人的 Claude Code 日常是这样的在终端敲一下claude然后丢一句话帮我看看这个 bug 怎么回事或者把这个模块重构一下。听起来没什么问题但实际跑起来你会发现模型是在一个近乎空白的上下文里开始干活的。它不知道你的项目用什么包管理器不知道你测试命令是npm test还是pnpm exec vitest不知道你对代码风格有没有偏好更不知道这次改动和上次某个讨论之间有什么关联。于是它花大量 token 在试探规则上先是猜猜错了被你纠正再猜。一次两次可以长期下来每次对话都重复这一套流程效率损耗相当可观。我见过最典型的场景同事让 Claude Code 改一个老模块的接口模型按照通用的 TypeScript 风格生成了一版优雅的代码结果仓库实际的代码风格是函数式 大量 JSDoc跟模型生成的完全是两个画风。同事改了半天才把风格对齐。这个问题的根源不是模型能力不够而是它缺一份这个项目该怎么写代码的上下文。1.2 模板的本质把团队口粮固化成上下文你可以把模板理解成给模型的一份入职手册。新同事入职不会直接丢给他一个需求让他开工而是要让他读 README、了解项目结构、熟悉代码规范、知道常用的命令和部署流程。模板做的事情完全一样只不过对象从人换成了 AI。具体到 Claude Code 的机制上这套入职手册分为两层。一层是CLAUDE.md它会在每次会话启动时被自动加载相当于常驻记忆。另一层是斜杠命令slash command存放在.claude/commands/目录下需要时用/触发相当于按需阅读的手册章节。这个区分很重要。CLAUDE.md放的是任何任务都必须知道的基线信息斜杠命令放的是特定任务的执行协议。如果把所有内容都塞进CLAUDE.md上下文会迅速膨胀反而干扰模型对当前任务的注意力如果所有内容都做成斜杠命令模型在开局时又缺少必要的项目背景照样会走弯路。我个人的比例参考CLAUDE.md控制在 40 到 60 行以内只写项目身份、技术栈、关键命令和不可违背的约束斜杠命令按场景拆每个命令文件控制在 80 到 120 行聚焦单一任务的执行步骤。这是我在几个仓库里试出来的比较舒服的范围。1.3 哪些项目和角色最受益也不是所有项目都适合重度模板化。我的经验是下面这几类场景收益最明显大型 monorepo 或多技术栈仓库模型需要同时理解多个子项目的边界、依赖关系和构建顺序没有项目级模板它很容易跨项目乱改。老项目维护代码历史包袱多、约定俗成的规矩多很多约束不在代码里而在维护者的脑子里模板可以帮你把脑子里那些隐性知识显性化。团队协作多个工程师共用同一个仓库时模板能统一 AI 产出的风格和流程减少 review 时的摩擦。高重复性工作如果你经常做代码评审、测试生成、依赖升级、批量重构这些场景天然适合固化成命令。反过来一次性脚本、纯探索性任务、或者你自己玩的小 demo不需要模板。硬要套模板反而拖慢速度。判断标准很简单这个任务你一周会做几次如果超过三次就值得做进模板。2. Claude Code 模板体系全拆解不止是提示词文件2.1 模板的三个层级全局、项目、命令Claude Code 的模板机制分几个层级理解它们的加载顺序是搭模板的第一步。用户级配置~/.claude/CLAUDE.md作用于你机器上的所有项目。适合放你个人的通用偏好比如回复时使用中文、默认不要修改锁文件、代码示例优先用 TypeScript这类跨项目稳定不变的东西。项目级配置项目根目录下的CLAUDE.md会在你进入该项目时自动加载。这是最核心的层级放的是这个项目独有的信息比如技术栈、目录结构、构建命令、测试方式、部署流程。命令级模板.claude/commands/目录下的 markdown 文件以斜杠命令形式按需触发比如/review、/test、/refactor。命令模板是异步加载的只在触发时进入上下文因此可以写得很详细不用担心常驻上下文膨胀。除了这三层如果你在用较新版本的 Claude Code还会接触到.claude/agents/目录下的子代理定义。本质上这也是模板的一种形式只不过它把角色设定 工具权限 执行流程打包成了一个独立的代理单元。我的建议是先从命令模板入手把流程跑顺了再考虑升级到子代理。子代理适合需要多轮自主执行的复杂任务比如扫描整个仓库的安全问题并把结果汇总成报告。2.2 命令模板的 frontmatter 与参数机制命令模板不只是纯文本提示词。每个.md文件的开头可以有一段 YAML frontmatter声明这个命令的描述、参数、以及允许使用的工具。一个评审命令的基础结构长这样--- description: 对指定范围的代码做一次结构化评审 argument-hint: 文件或目录路径 [评审深度] allowed-tools: Read,Grep,Glob --- # 代码评审任务 你正在对 {{$ARGUMENTS}} 指定的代码范围进行评审。 ...$ARGUMENTS是这条命令被触发时用户传入的参数。比如用户输入/review src/foo.ts那么{{$ARGUMENTS}}就会被替换成src/foo.ts。更细化的场景你可以让用户在参数里指定评审深度比如/review src/foo.ts --depthfull然后模板里通过解析参数决定是只看 diff 还是连带调用方一起分析。allowed-tools这个字段我一开始没在意后来才发现它极其重要。它限制了模型在处理这条命令时能调用哪些工具。比如评审命令只给 Read、Grep、Glob 这类只读工具不给 Write 和 Edit等于给模型上了锁防止它在评审过程中顺手修了某个文件。你在设计模板时一定要养成每个模板默认最小化工具权限的习惯。权限越小的模板就越不容易出安全事故。正文部分才是模板的核心。写正文时有一个容易被忽略的点命令模板里应该包含对模型输出格式的约束。比如评审命令要求它最后必须输出一个问题清单每一条标注严重级别、影响范围、建议方案。没有这个约束模型很容易写一段流水账信息密度很低你看了还得自己归纳。2.3 官方模板仓库和开源生态的参考价值如果你不想从零开始一个很好的起点是官方维护的anthropics/claude-code-templates仓库。这个仓库存放了大量按场景分类的模板覆盖代码评审、测试生成、重构、文档编写、安全审计等常见任务我最初就是从里面挑了几个命令直接拿来用再按自己项目的需求改。印象比较深的几个官方的测试生成模板会要求先列出待测函数的输入空间和边界条件而不是直接让模型写几个测试用例官方的重构模板强调先描述行为契约再动手改代码。这些设计思路其实反映了同一个原则模板要引导模型先想清楚再动手执行。开源社区里的第三方模板也值得翻一翻尤其是那些针对特定框架的比如 React 组件评审模板、Python 迁移模板、SQL 查询优化模板。但要注意社区模板质量参差不齐很多只是把提示词换了个名字。拿到一个模板先看它是否包含上述的步骤拆解 输出格式约束 工具权限控制三件套缺任何一件效果都会打折。3. 从零搭一套真正能用的模板我的工程化过程3.1 先盘点重复性工作再动手写模板我第一次搭模板的时候犯过一个错误对着屏幕想该写哪些模板结果写出来的都是自己想象中会用到的功能实际使用频率很低。后来我换了一个方法先不做任何归档正常用 Claude Code 干活一个星期每次发现这句话我上周也说过或者这份说明我每次都在开头贴就把这个场景记下来。一周下来我统计出了自己最高频的几个场景后面加上了频率和每次损耗的上下文量工作类型每周触发次数每次需要交代的关键信息最常出错的点代码评审8 次以上评审范围、关注点、输出格式只读代码不看调用方测试生成5 次以上被测函数边界、mock 方式生成无效边界用例重构3 到 5 次行为契约、依赖关系改完行为变了报错排查频繁日志位置、复现步骤跳过环境因素依赖升级低频升级范围、兼容性要求盲目更新破坏性变更排序之后你会发现值得做成模板的不一定是频率最高的而是每次交代信息成本最高的那几个。比如报错排查虽然频繁但每次的上下文差异很大模板能提供的增量有限代码评审和重构则是典型的交代成本高、规则可复用的场景最值得模板化。3.2 写第一版 CLAUDE.md项目档案要克制项目根目录的CLAUDE.md是模板体系的基座但这里最忌讳写成一本百科全书。我的原则是只写模型无法轻易从代码里推断出来的信息可以推断出来的通通不写。下面是我某个 TypeScript monorepo 项目的第一版CLAUDE.md的大致结构# 项目概况 这是一个 pnpm workspace 管理的 monorepo包含 apps/web、apps/api、packages/core 三个包。 # 技术栈 - 框架Next.js 14 Fastify - 语言TypeScript 5.xstrict 模式 - 数据库PostgreSQL通过 Drizzle ORM 访问 - 测试Vitest Testing Library # 关键命令 - 安装依赖pnpm install - 开发模式pnpm dev - 类型检查pnpm typecheck - 单元测试pnpm test # 不可违背的约束 - 不要修改 packages/core 的公共 API除非有明确授权 - 所有新增代码必须带对应的单元测试 - 禁止在服务端代码中直接引入 client 包注意最后一段我专门留了一个不可违背的约束区块。这是整个CLAUDE.md里最有价值的部分。通用规范和代码风格模型可以从代码里学到但这类人和人之间的约定它无法从代码里推断出来必须显式告诉它。还要提醒一点CLAUDE.md写完之后如果你的项目里本来有多个入口目录或者脚本一定要把最常用的几条命令写全。模型在终端里执行命令时如果不知道用什么包管理器它大概率会猜npm然后你的 pnpm 项目就多了一堆node_modules和锁文件变更。3.3 把高频动作做成斜杠命令有了CLAUDE.md作为基座下一步就是把高频动作拆成斜杠命令。我习惯在每个项目的.claude/commands/目录下按动作-对象的方式命名比如review.md、test.md、refactor.md这样触发时输入/review、/test、/refactor即可。命令模板的撰写有一组我一直在用的骨架任务定义用一段话说明这个命令要完成什么任务以及任务的成功标准。前置检查要求模型在执行前先读取哪些文件、确认哪些信息。这是防止它盲目动手的关键。执行步骤分步列出任务的操作流程每一步都给出具体的产出物。输出格式规定最终回复的结构比如问题清单迁移报告测试计划。自检清单要求模型在结束前逐项检查自己的输出是否符合项目规范。以review.md为例它的前置检查部分要求模型先运行git diff查看改动范围再读取被改动文件的完整内容然后列出这个改动涉及的调用方有哪些。没有这一步模型经常会拿着半截代码开始点评评得头头是道实际上连这个函数在哪被调用都没搞清楚。3.4 模板中的变量、条件与权限控制斜杠命令之所以比普通提示词更强大是因为它支持参数注入。$ARGUMENTS可以捕获用户在触发命令时输入的参数你的模板可以根据参数改变执行流程。我经常用的一个写法是在模板里处理可选参数--- description: 为指定函数生成单元测试 argument-hint: 待测试的目标路径 [--coveragehigh|basic] allowed-tools: Read,Grep,Glob,Bash --- # 测试生成任务 目标对象{{$ARGUMENTS}} 如果参数中包含 --coveragehigh则需要额外生成边界条件测试和异常路径测试 如果没有指定则生成核心功能测试即可。这种条件写法让一条命令覆盖多种使用场景而不是一个场景就得建一个模板。我见过有些人把/test-basic、/test-full、/test-edge建成了三个模板维护成本直接翻三倍实际上用一个参数就能解决。权限控制方面这里再展开一下。每个命令都建议显式声明allowed-tools不要把所有命令都配成同一套工具。比如只读类任务就用Read,Grep,Glob需要执行测试的命令才加Bash。我有个教训是早期给/refactor配了Write,Edit,Bash全套工具结果模型在一次重构中擅自跑了一个会修改数据库 schema 的迁移脚本差点出事。从那之后所有命令的allowed-tools我都是逐条审过的。4. 三个高频模板的打磨实录4.1 代码评审模板从看一眼到按规范排查代码评审是我用得最多的斜杠命令也是迭代次数最多的一个。最初的版本写得很简单就是请评审以下代码改动指出潜在问题。跑了几次之后发现模型确实能指出一些问题但很多都是不痛不痒的小毛病真正关键的问题——比如改动影响到了被其他模块引用的公共函数——反而漏掉了。问题出在模板没有强制模型建立改动影响面的认知。后来我在模板里加了三道前置步骤第一运行git diff获取精准的改动内容而不是让模型自己去猜改了什么。第二让模型列出所有调用了改动目标的外部代码逐一面读取。第三要求模型区分改动引入的行为变更和改动修复的行为异常前者必须在输出中重点高亮。这是最终版评审模板的核心片段# 代码评审任务 评审对象{{$ARGUMENTS}} ## 前置步骤 1. 运行 git diff --stat 和 git diff确认改动范围和具体变更内容。 2. 找出所有调用了本次改动目标函数/类/组件的外部代码读取并记录它们对改动目标的假设。 3. 确认改动是否涉及公共 API、持久化数据结构或对外协议。如果涉及必须在评审结论中单独列出。 ## 输出格式 ### 严重问题 ### 潜在风险 ### 改进建议 ### 行为变更清单这个模板跑了一段时间后我统计过大概有六成以上的评审结果可以直接拿来作为 PR 的 review 意见剩下四成也只需要小幅调整措辞。相比之前那种流水的点评质量稳定性提升得非常明显。还有一个细节评审模板一定要拒绝修复代码。我专门在模板里加了一句你的任务是发现问题并描述不要直接编辑文件。因为评审和修码是两件不同的事混在一起模型往往会直接给出修改后的代码反而掩盖了评审结论的清晰度。4.2 重构模板安全迁移老代码重构是另一个我踩过大坑的场景。之前有一次我让 Claude Code 把一个 3000 行的老类拆成几个模块它拆得很勤快但拆完之后测试挂了十几个——因为它把某些带有副作用的方法搬到了模块顶层执行顺序都变了。后来我在重构模板里强制加入行为契约概念规则只有一条重构前后同一输入必须产生同一输出同一调用顺序必须产生同一副作用顺序。模板要求模型先做这三步列出被重构对象的全部公共方法和属性定义每个方法的行为契约。梳理依赖关系图包括import、运行时注入、事件监听、全局状态读写。输出一份迁移方案说明哪个方法迁到哪个模块、迁移后依赖方向是否变化。只有这三步做完并让使用者确认之后模型才能开始写代码。这是重构模板里最核心的一段# 重构任务 目标对象{{$ARGUMENTS}} ## 第一步行为契约清单 逐一列出目标对象的公共方法对每个方法描述 - 输入参数及其类型约束 - 返回值 - 是否修改外部状态文件、数据库、全局变量、事件发射 - 异常时对外表现 ## 第二步依赖关系图 列出目标对象的依赖和被依赖关系。 ## 第三步迁移方案 基于上述信息输出迁移方案包括目标模块划分、依赖方向、需要同步更新的调用方。 在用户确认迁移方案之前不要修改任何代码。加了这套步骤之后重构任务的安全性明显提高模型不再会为了拆得干净而改变行为。这套思路后来我也用在了依赖升级上——升级之前先列破坏性变更清单再决定升级策略而不是直接pnpm update一把梭。4.3 自动化测试模板让生成用例有套路测试生成模板的设计重点不在写测试代码本身而在生成哪些测试的决策过程。模型如果不假思索地开始写往往会写出一堆覆盖最优路径的 happy path 用例边界条件和异常路径一片空白。我的测试模板要求模型按以下顺序工作先识别被测目标的输入空间列出参数的正常值域、边界值、空值、非法值。再识别外部依赖包括 API 调用、数据库读写、时间函数、随机数。然后生成一份测试用例清单要求使用者确认后才逐条写代码。模板的一个关键提示词片段# 测试生成任务 目标函数{{$ARGUMENTS}} ## 测试计划阶段 1. 列出被测函数的全部输入参数标注类型和合法值域。 2. 针对每个参数列出边界条件最小值、最大值、空值、溢出值。 3. 如果函数与外部系统交互列出需要 mock 的外部依赖。 4. 输出一个测试用例清单每个用例标注输入、预期输出、覆盖类型。 在输出用例清单并等待用户确认之前不要写任何测试代码。这样做的好处是双重的一方面确认过程能让使用者补上模型不知道的业务规则另一方面模型在写代码前已经理清了思路生成的测试代码质量更高很少出现断言写错但测试通过的情况。我统计过加了确认步骤之后测试用例的有效率提升了大概三成。5. 团队级模板管理版本、评审、演进5.1 模板也是代码要走版本管理模板一旦进入团队协作场景就不再是你个人~/.claude里的私物而是一份需要被审查、被测试、被维护的工程资产。我的做法是把团队模板单独建一个 git 仓库里面包含CLAUDE.md和.claude/commands/的通用版本各个项目通过 git submodule 或 vendoring 方式引用。这里的核心逻辑是模板的改动会直接影响所有使用它的人下一次对话的输出质量所以这个改动必须走评审流程。我们团队内部模板更新走常规的 PR 流程至少一名同事 review合并之后各项目拉取更新。规则和代码评审大致相同但多了一条模板不经过实测验证不允许合并。哪些算实测验证我要求提交者在 PR 描述里贴出至少一次使用该模板的真实对话摘要证明模板确实能引导模型产出符合预期的结果。没有实测的模板reviewer 就只能看文字猜测效果这等于盲改。5.2 定期回收与失效清理模板也有腐烂问题。我见过一个团队模板目录从最初的 5 个增长到 60 多个很多人半年都没用自己创建的模板但也没人敢删。这是典型的收藏癖式模板管理。我给自己定了一条规则每个模板的 frontmatter 里加一个last-used字段每季度检查一次如果连续两个月内没有被触发超过三次就进入待删除清单再给团队两周缓冲期仍无人认领就直接删除。这个规则的执行效果有两个一是迫使每个模板都有明确的用户场景二是让模板总量保持可控。我手头个人项目的模板数长期维持在 6 到 10 个左右团队级仓库则控制在 20 个以内。数量超过这个阈值模板之间的边界就开始模糊使用者会不知道该用哪个。还有一类失效更隐蔽模板里写的命令、路径、参数已经过时。比如某个模板写了运行npm run db:migrate进行数据库迁移后来项目改成了pnpm drizzle:migrate模板还停在旧命令上。这种失效比没有模板更危险因为模型会非常听话地执行模板里的内容照着废弃命令跑一遍然后报出一堆看不懂的错误。我的对策是在模板的执行步骤里尽量写如何发现正确命令而不是直接写命令是什么。比如让模型先读取package.json的 scripts 区块确定迁移命令而不是在模板里硬编码。把信息如何获取写进模板模板就自动具备了对项目变更的适应性。5.3 让模板适配不同水平的使用者同一个模板新手和老手的使用方式完全不同。新手需要的是保姆级引导告诉他先运行什么再观察什么遇到什么情况选哪个分支。老手需要的是极简指令一句话说明目标剩下的交给模型。我的方案是在团队模板仓库里做两套命令比如review和review-standalone。前者是完整结构化流程每一步都做了详细引导适合初接触模板的成员后者要求模型自己判断该读什么文件、用什么步骤适合已经熟悉团队规范的成员。两套模板的核心规则是一样的差异性主要体现在明确程度上。举例来说review模板要求模型必须先运行git diff再读取调用方review-standalone则只是说先掌握改动影响面再评审。这样做的本质是让模板库同时覆盖培训和提效两个目标而不是用一套流程将就所有人。6. 避坑指南我踩过的模板相关坑6.1 上下文膨胀模板越长模型越分心模板最常踩的坑是越写越长。一开始你觉得每句话都有用慢慢地这个文件加到几百行那个命令写了两千字。但模型的注意力是有限的模板里的每一条指令都在占用认知资源。我有一次在CLAUDE.md里写了上百行项目风格指南结果模型在生成代码时反而犹豫不决时不时在几个规则之间打转产出速度明显下降。把CLAUDE.md砍到 50 行之后问题立刻缓解。这里给一个可量化的经验值CLAUDE.md的 token 长度尽量控制在 1000 token 以内一个命令模板总长控制在 2000 token 以内。超过这个量级你要么在拆模板要么在删内容。模板是给模型减负的不是给它上刑的。6.2 过时模板比没有模板更危险前面提到过命令失效的问题这里我再补一个具体的例子。我有个项目曾经在模板里写了所有测试必须通过pnpm test:ci运行后来测试架构调整这个命令被移除了。一位同事用/test命令触发模板时模型反复执行一个不存在的命令然后尝试各种补救最后在错误的文件里生成了大量无用代码。整个流程跑了一个多小时产出为零。从那以后我养成了一个习惯模板中凡是涉及命令、路径、文件名的内容都加一句以项目当前实际配置为准并建议模型在引用前先读取配置文件确认。这个改动杀死了大量由于项目迭代带来的模板过时问题。6.3 模型版本和模板兼容性Claude Code 底层模型升级之后模板的效果会有微妙的变化。有些模板是为了规避旧模型的某些缺陷设计的比如要求模型不直接写代码而先列清单当新模型已经天然具备先计划后执行的能力时这部分冗余指令反而会拖慢节奏。我处理的办法是在模板的 frontmatter 里标注这个模板适配的模型版本范围比如applies-to: claude-3-5-sonnet, claude-3-7-sonnet。每次模型大版本升级我专门抽半天时间把所有模板都跑一遍冒烟测试检查哪些模板需要更新或简化。这套定期体检机制比遇到问题再修要好得多因为它能提前发现冗余这类不会直接报错的隐性退化。6.4 敏感信息与权限边界模板目录会被模型自动加载这意味着任何写在模板里的内容都会被模型当作知识库使用。如果你的模板里有数据库连接串、API key、内部域名这些信息几乎等于暴露给了每个能操作 CLI 的人而且会被不知情地写进模型生成的代码或回复中。我在团队里定的红线是模板中禁止出现任何形式的密钥、凭据、内网地址涉及敏感配置的场景模板只写从环境变量DATABASE_URL中读取连接信息而不写实际值。因为模板的本质是上下文上下文越干净模型的输出就越安全。另外allowed-tools的权限边界也很重要。每个命令模板都必须按最小权限原则配置宁可少配不要多配。只读任务就只给读工具涉及写文件的任务才给写工具涉及执行脚本的任务才给 Bash。我见过最夸张的案例是某个团队的安全审计模板居然配了 Write 权限模型做审计做到一半直接改了一个文件。这种事故看似荒诞实际发生的概率远比你想象得高一定要在模板里兜住。还有一个容易被忽略的点团队模板仓库本身的权限管理。我建议对.claude/commands/目录的写权限做严格的代码 review 控制因为一个恶意或错误的模板它的影响范围是整个团队所有成员的所有 AI 会话。最后说一点个人体会。模板这个东西价值不在于让 AI 做得更快而在于让 AI 每一步都做在你画定的圈内。它像是给模型戴了一副校准过的眼镜让模型在看项目代码时自动过滤掉那些不该碰的东西聚焦在真正重要的部分。我目前的下一步是把模板的触发频率和产出质量做成简单的统计表比如每个模板被触发后的改动接受率、返工率积累一定样本量之后再来和大家分享这组数据。如果你也在用 Claude Code 做正经项目我的建议是先从一条最高频的斜杠命令入手跑顺一个场景之后再把这套方法论复制到其他场景不要一上来就追求大而全的模板库。