Claude Code 模板库实战：构建可复用的上下文工程体系

最近我把攒了很久的一个仓库整理成了公开的claude-code-templates说句实话这些模板不是灵感一闪写出来的而是日常用 Claude Code 做代码审查、补测试、重构老模块时被一次次重复提问逼出来的。如果你也遇到过这种情况——让 AI 帮忙看代码结果它每换一个项目就要重新理解一遍你们的代码风格、测试框架和禁忌清单或者同一个审查请求你每天要打三遍——那你缺的不是更好的提示词而是一套固定下来的模板库。这篇文章会围绕claude-code-templates的搭建思路展开我会复盘为什么默认配置不够用、一套模板体系应该分成哪几层、我实际维护了哪些模板、以及踩过哪些坑。内容不追求代码补全技巧而是想把“上下文工程”这件事做到可持续、可复用。1. 为什么需要自己的 claude-code-templates直接抄官方配置还不够吗1.1 Claude Code 默认行为与“一问一答”的局限Claude Code 默认使用方式其实很简单在终端里运行claude然后像聊天一样描述任务它根据当前仓库的内容去读文件、跑命令、生成修改。对个人项目来说这种一问一答基本够用但一旦进入团队项目或者长期维护的代码库问题就出现了每次对话都是一次全新会话AI 不会自动记住你们团队的编码规范、目录约定、提交风格除非你把这些信息重复粘贴进去。有人会反驳说可以用聊天上下文里的信息。但实际体验是同一套审查规则我今天讲一遍明天新开一个会话又得讲一遍。更麻烦的是规则经常存在某个人的大脑里换个同事来问AI 给出的建议就完全不是同一套标准了。这时候就需要claude-code-templates这种结构化的“行为说明书”让规则落在文件里每次启动 Claude Code 时自动生效。1.2 模板解决的三类核心问题我总结下来模板主要解决三件事规范一致性、重复效率、知识沉淀。规范一致性解决的是“十个人问出十个结果”的问题重复效率解决的是“同一个审查/测试/重构套路反复描述”的问题知识沉淀解决的是“项目里踩过的坑只存在于聊天记录”的问题。常见问题没有模板时的表现有模板之后团队规范每个人对代码风格理解不同统一在 CLAUDE.md所有会话按同一套规则走重复任务每次重新描述审查流程和标准一个/review命令自动执行完整审查流程经验沉淀踩坑记录散落在群聊和 issue写入模板下次 AI 自动规避同类问题所以我的结论很明确官方配置文档只是告诉你“有 CLAUDE.md 和 commands 这种东西”而真正让 Claude Code 高效运转的是你自己维护的一套模板体系。这套体系可以很小但必须围绕自己的项目长出来。1.3 “模板”和“提示词”的区别前者是资产后者是消耗品很多人把模板等同于一堆提示词的集合这是一个误区。提示词是即时输入的一段描述用完就没了模板是放在.claude/目录下的文件每次会话都会被自动加载或按需调用。模板可以进 Git、可以 review、可以版本化提示词做不到。打个比方提示词相当于你每次下馆子都临时跟厨师说“少盐、不要香菜、多放辣”模板则是一张写好的定制菜单下次直接说“按老规矩来”。Claude Code 的CLAUDE.md就是那张菜单claude-code-templates就是一套精心设计过的菜单集。2. claude-code-templates 的三层骨架CLAUDE.md、commands 与 hooks2.1 模板到底放在哪里目录结构怎么搭Claude Code 的模板体系主要落在项目的.claude/目录下。我目前维护的结构是这样的.claude/ ├── CLAUDE.md ├── commands/ │ ├── review.md │ ├── test.md │ ├── refactor.md │ └── commit.md └── hooks/ └── settings.jsonCLAUDE.md是全局记忆文件相当于项目给 AI 的一份常驻说明commands/下的每个 Markdown 文件就是一个自定义斜杠命令用户输入/review就会调用review.md里的完整指令hooks/settings.json则用于配置事件钩子比如在读取某个文件前自动注入上下文。这三层各司其职缺一不可。如果你只想要一个最小可用的模板那只要一个CLAUDE.md就够了但随着项目和团队变大commands 和 hooks 会带来质的改变。因为CLAUDE.md是常驻上下文不适合太厚而 commands 是按需加载的可以把很长的操作流程塞进去不会浪费日常对话的 token。2.2 CLAUDE.md 模板设计写什么、不写什么CLAUDE.md是最容易被写坏的文件。我见过很多人把整个 wiki 粘贴进去结果 AI 每次读上下文都要消耗大量 token核心指令反而被淹没。正确做法是CLAUDE.md 只写必须记住的约束、项目概览和常用命令入口不写长篇背景故事。我的CLAUDE.md模板会包含以下几块项目一句话简介让 AI 知道这是什么系统技术栈是什么。非功能性规则比如“禁止直接修改 package-lock.json”“提交信息必须符合 Conventional Commits”。常用命令测试、构建、lint 的具体命令。架构标记核心模块在哪些目录哪些文件不要动。常见坑列表列出容易误导 AI 的陷阱比如“不要用process.env直接读配置统一走config模块”。核心原则是克制。每条规则都要问自己如果 AI 不知道这条会不会犯明显错误如果不是就不要写进去。CLAUDE.md相当于 AI 的“员工手册”太厚了没人会看AI 也会抓不住重点。2.3 自定义命令模板把重复动作变成斜杠命令自定义命令是claude-code-templates里最实用的部分。它不占用常驻上下文而是等你在终端里输入/xxx时才加载对应文件。这意味着你可以把很完整的流程写进去把“告诉 AI 每一步怎么做”变成一次斜杠命令。一个标准的review.md文件长这样--- description: 按团队规范执行代码审查 allowed-tools: Read, Grep, Glob, Bash --- 请以资深代码审查者的身份对当前变更的代码进行审查。 审查必须覆盖以下维度 1. 正确性是否存在逻辑错误、边界条件遗漏。 2. 安全性是否引入了注入、越权、数据泄露风险。 3. 可维护性函数是否过长、命名是否清晰、是否有重复代码。 4. 测试覆盖关键路径是否缺少单元测试或集成测试。 先读取 git diff列出所有变更文件。 对每个问题给出文件路径、行号和严重级别BLOCKER / MAJOR / MINOR。 最后用表格汇总并给出修改建议。注意前面的description字段它是在用户敲/review后展示的简短说明。allowed-tools可以限制命令能使用哪些工具避免审查任务被 AI 误触发写文件的工具。这个机制特别适合把高风险操作锁死。2.4 Hooks在事件节点自动触发模板逻辑Hooks 比 commands 更底层一些。它是 Claude Code 在特定事件节点比如读文件、执行命令、会话结束触发的自定义逻辑一般配置在.claude/hooks/settings.json。我最早觉得 hooks 很鸡肋直到用了一个场景每次 Editor 编辑文件后自动跑一遍 ESLint 的增量检查。{ PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: npx eslint --fix $CLAUDE_FILE_PATHS, timeout: 30 } ] } ] }这个配置的意思是只要 AI 修改了文件就自动对相关文件跑一次 eslint --fix。虽然 Claude Code 本身也能通过对话要求它做完修改后检查 lint但通过 hook 触发更可靠不用每次都把同样的话写进 prompt。hooks 能把一些“固定动作”变成规则铁律。不过 hooks 也不是越多越好。每加一个 hook就多一层复杂性出错时还不好调试。我一般只加两类 hook自动格式化和自动跑相关测试。更复杂的流程建议放进 commands而不是 hooks。3. 从零搭建自己的模板库一套我实际在用的结构3.1 模板库的目录设计既然要做claude-code-templates就不能只在一个项目里塞几个文件而是要建一个独立的仓库去维护这些模板然后同步到各项目里。我正在维护的模板仓库结构大致如下claude-code-templates/ ├── core/ │ ├── global-rules.md │ └── common-commands.md ├── roles/ │ ├── senior-engineer.md │ ├── security-review.md │ └── technical-writer.md ├── workflows/ │ ├── pr-review.md │ ├── add-test.md │ └── refactor-module.md └── projects/ ├── frontend/ │ └── CLAUDE.md └── backend/ └── CLAUDE.mdcore/放的是跨项目都适用的通用规则比如“不要编造不存在的 API”“修改前先读取原文件”“谨慎处理删除操作”等。roles/放的是不同角色视角的模板比如让 AI 以“安全审查者”身份工作时需要关注什么。workflows/则按业务动作拆分比如审查 PR、补测试、重构老代码。projects/下放的是具体项目定制的CLAUDE.md每个项目一份。这样分层的好处是核心规则和角色模板可以被多处引用不会变成每个项目里都复制一份的巨大文件。理论上你可以把 core、roles、workflows 拼装成任意项目需要的CLAUDE.md。3.2 core/ 与 roles/ 分层解决“一次性上传太多上下文”的问题为什么一定要拆成 core、roles、workflows因为 Claude Code 的上下文窗口是有限的。如果你把“全局规则 安全审查角色 重构流程 项目特定约定”全部堆到一个CLAUDE.md里那 AI 每次会话都会带着这一大坨内容运行既费 token又容易让关键规则被淹没。拆开之后就灵活多了。全局规则永远加载角色模板和流程模板按需加载。你想让 AI 做安全审查就直接/security-review它会加载roles/security-review.md里的约束你想做重构就/refactor-module它知道先写计划再动手。每个模板只在需要时出现上下文保持“够用就好”。这个设计思路是从函数式编程里偷过来的按需加载、组合优于继承。模板与模板之间通过互相引用来协作而不是把所有内容复制进同一个文件。3.3 每个模板维护两个版本简洁版和详细版我早期犯过的错误是所有模板都写得非常详细参数很多步骤很细。结果 AI 执行力强了但人看模板的时候很痛苦因为每一步都在限制反而让灵活判断的空间变小。后来我给每个 command 模板维护两个版本简洁版只有 3-5 个关键步骤适合日常任务让 AI 有发挥空间。详细版包含完整的 checklist、评分标准、输出格式适合对边界敏感的场景比如安全审查、生产环境变更。写模板时我用 frontmatter 里的一个自定义字段variant来区分然后在命令描述里注明什么时候用哪个版本。实际体验是模板越短AI 的主动思考越多模板越长一致性越高。你需要根据任务对“一致性”和“创造性”的需求来做取舍不要一刀切。4. 实战拆解代码审查模板、单测生成模板、重构模板4.1 代码审查模板从“你帮我看看”到“按规范审查”我最常用的一个模板就是/review。在没有模板之前我会说“帮我看看这段代码有没有问题”结果 AI 给出的反馈很泛一会儿说命名不行一会儿说性能可能有问题但都不是团队真正关心的点。后来我把审查维度全部写进模板效果立刻不一样。这里是我正在用的review.md内容节选--- description: 按团队规范执行代码审查 allowed-tools: Read, Grep, Glob, Bash --- 你是团队里的资深代码审查者。请聚焦以下面维度进行审查 - BLOCKER会导致功能错误、安全漏洞或严重性能回退的问题。 - MAJOR需要修改但不会阻塞合并的问题包括可维护性缺陷。 - MINOR建议性改进包括命名、注释、格式。 请先获取 git diff 的统计信息然后逐个文件审查。 输出格式要求 1. 先列出 BLOCKER 和 MAJOR 问题的表格包含文件路径、行号、问题描述。 2. 再列出 MINOR 建议用列表呈现。 3. 如果没有发现任何 BLOCKER请明确说明“可以合并但需关注以下改进点”。这个模板最关键的地方是定义了严重级别和输出格式。AI 一旦了解 BLOCKER/MAJOR/MINOR 的含义它就会主动去分级而不是把所有问题一视同仁地列出来。你也不用再一边读反馈一边揣摩哪条重要了。4.2 单测生成模板绑定语言与框架约定很多团队的测试风格其实很固定比如前端项目常用 Vitest 和 Testing Library后端常用 pytest 或 JUnit。但 AI 默认不知道这些你不说它可能给你生成 JUnit 风格的前端测试。所以/test模板的核心价值不是让 AI 写更多测试而是让它按你们团队的测试约定来写。我的单测生成模板长这样--- description: 为指定文件生成匹配现有风格的单元测试 allowed-tools: Read, Grep, Glob, Bash --- 先读取被测试文件的完整内容然后读取其同级目录下已存在的测试文件分析现有测试风格。 必须遵守 1. 使用项目已有的测试框架通过 package.json 检测。 2. 新测试文件放在与被测文件同级的 __tests__ 目录或同名 .test.ts 文件。 3. 命名规则describe 中用模块名it 中用行为描述。 4. 只测公开接口不测私有实现。 5. 对边界条件至少补充两个用例空值、异常输入。 6. 不要修改被测文件除非发现明显 bug 并说明。 完成后运行测试命令 npm test -- --runInBand 文件名 并确认测试通过。重点是“先分析现有测试风格”这一步。大多数时候 AI 写单测最大的问题不是不会写而是写得和团队风格不一致。强行定义“必须用 fixture、必须 mock 外部请求”会让模板很长但能保证测试风格统一。这也是claude-code-templates最大的价值它把团队潜规则变成了显式约定。4.3 重构模板先写迁移计划再动手重构是 Claude Code 比较容易“莽撞”做坏的任务尤其涉及跨模块改动时。很多次它直接开始改代码改到一半我发现方向不对浪费了大量 token 和时间。后来我在/refactor模板中加入了一条铁律在没有输出完整迁移计划前不允许修改任何文件。我的refactor.md核心部分--- description: 重构模块前先给出迁移计划确认后再执行 allowed-tools: Read, Grep, Glob, Bash, Edit --- 你需要完成一次模块重构。在动手之前必须完成以下步骤 1. 读取目标文件的全部内容并用 grep 搜索它的引用位置。 2. 输出重构计划包括改造点、影响文件列表、兼容策略、回滚方案。 3. 等待用户明确输入“继续”后才开始修改文件。 4. 修改时优先保持接口兼容不改变外部调用方式。 5. 每完成一个阶段运行一次相关测试给出结果再继续下一步。这个模板的设计核心是“分阶段确认”。不是让 AI 一口气全做完而是每走一步都汇报一次把控制权交回开发者手里。对于大型重构我甚至会把上面的步骤扩展成一个交互式向导让 AI 每完成一步就停下来等我确认。虽然会多几次交互但换来的是对代码库的完全掌控。5. 模板工程化版本管理、团队共享与持续迭代5.1 用 Git 维护模板库并把模板同步到项目claude-code-templates首先是一个仓库。我发现把模板当代码一样管理很重要因为模板本身就是一种代码资产。我给每个模板单独一个文件提交信息里写清改动原因。要改动时走提交流程而不是直接在项目里悄悄改。同步到项目时我一开始用的是“复制粘贴”大法但很快发现不同项目的模板会漂移。后来我用了一个简单脚本把模板仓库 clone 到本地后通过rsync将选定的模板同步到不同项目的.claude/目录。脚本会做一件事比较项目中的.claude/与模板仓库中的profiles/project/不一致时提示差异而不是无脑覆盖。# sync-templates.sh project$1 rsync -av --delete \ ~/claude-code-templates/projects/$project/ \ ~/work/$project/.claude/这个方式很朴素但对团队足够。如果你有条件也可以用 Git submodule 或专门的配置管理工具不过对大多数团队来说一个带 diff 提示的同步脚本已经能避免“模板改了但项目没更新”的问题。5.2 如何让团队愿意使用同一套模板技术问题好解决人的问题才难。很多团队不是没有模板而是每个人都有自己的私有模板或者干脆凭感觉。要让claude-code-templates成为团队公约光把文件放进仓库是不够的。我做了三件事有效提升了使用率模板内置团队规范让 AI 的输出符合团队已有习惯而不是让人去适应 AI 风格。模板尽量轻量每个 command 控制在 30-50 行避免读起来像一篇论文。把模板评审纳入代码评审谁改了模板要写说明并且接受 review。另一个很有用的做法是在新成员入职时把模板仓库作为“AI 编码规范”讲一遍。新人不用背项目背景直接看CLAUDE.md和几个核心命令就能让 Claude Code 按项目规范工作。这比传统的文档效率高很多。5.3 模板的“轻”与“重”什么时候必须拆开CLAUDE.md最怕臃肿commands 最怕碎片化。我制定了一个简单规则如果一条规则适用于所有项目放进core/global-rules.md。如果一条规则只适用于某个角色或某个任务放进对应的roles/或workflows/。如果一个 command 超过 80 行我会警惕考虑是不是应该拆成多个子命令。如果一个 project 的CLAUDE.md超过 50 行我会重新审视哪些内容可以移到 commands 中按需加载。这个“轻与重”的平衡直接影响模板的使用体验。一开始会觉得所有内容都很重要但在真实使用中你会发现模板越精简AI 表现越聪明。因为过多的约束会限制 Claude 的推理自由度它会把注意力放在满足你写的各种条条框框上而不是真正去想代码该怎么写。6. 踩过的坑与效果验证6.1 模板太厚反而让 AI 抓不住重点我第一次整理模板时把团队 wiki 里所有内容都塞进了CLAUDE.md包括公司历史、项目背景、模块演进过程。结果每次会话开头都要消耗 2000 多 token 去读取这些内容AI 的回答变得非常保守总觉得有什么隐藏规则没有满足。后来我把所有背景内容移到docs/里CLAUDE.md只留硬约束和入口整体效果立刻改善了。这个坑让我意识到CLAUDE.md不是越全越好而是越“锐”越好。每个句子的价值都应该被反复审视不能带来行为变化的句子删掉就是。6.2 指令冲突全局规则和局部命令打架模板分层之后出现了一个新问题CLAUDE.md里说“必须使用 pnpm”但某个 command 模板里为了兼容旧项目写了“使用 npm”。这种冲突会导致 AI 陷入困惑有时它会在一次会话里同时遵守两条相反的指令。解决方案是在模板库里加一条元规则具体命令优先于全局规则项目配置优先于通用配置。同时在CLAUDE.md里写清楚这条优先级让 AI 遇到冲突时知道怎么办。更重要的是模板改了之后要定期跑一遍“冲突扫描”用 grep 搜一下所有模板里是否同时出现互相矛盾的措辞。6.3 不要过度限制工具权限allowed-tools是个好机制但限制过头会让模板无法完成任务。比如我最初在/test模板里只允许Read和Bash结果 AI 无法写文件测试生成方案变成了一堆建议而不是实际代码。后来我放宽到允许Edit并增加“只能编辑测试文件”的约束才达到预期。这个教训是限制工具权限的目的是降低风险不是制造障碍。每个allowed-tools的配置都要以“这条命令大概率需要什么工具”为出发点。宁可放手让 AI 做再通过模板里的白名单目录去约束范围也不要卡死所有写操作。6.4 模板带来的收益如何量化很多人会问搞这一套claude-code-templates到底值不值我的量化方式是记录任务完成过程中的“来回次数”。比如审查一个 200 行变更没有模板的时候我可能需要和 AI 来回沟通五六次才能得到一份符合团队口味的报告有了模板之后一次/review就能拿到可用的表格。这个变化是可感知的。另一个指标是“一次性通过率”也就是 AI 生成的测试/重构方案是否需要大幅返工。加入规则之后测试文件一次性通过率从最初的两成提升到了六成以上。这背后不是 AI 变强了而是模板把“团队经验”前置给了它让它少走了很多弯路。这些数字不一定适合所有团队但只要你留意总能找到适合自己的度量方式。6.5 我还会继续迭代的方向目前这个claude-code-templates仓库还在更新我下一个阶段想做的改进有两块一是把 hooks 做成“认证过的模板”让 AI 自动执行 lint 和测试时不至于误伤代码二是把核心模板转成一个可交互的初始化向导让你用一条命令就能生成一套适合自己项目的模板。踩过这些坑之后我的体会是Claude Code 的能力上限很大程度上由你给它的信息和约束质量决定。模板不是用来束缚它的锁链而是让它的输出更贴近你真实需求的校准器。如果你也在维护自己的模板建议先从最困扰你的一个重复任务开始把它写成一个commands模板跑一个月后再回头看看大概率比拍脑袋设计的全套体系更容易落地。