Claude Code 模板实战：从 CLAUDE.md 到子代理，再到接入 DeepSeek

聊到 claude-code-templates 这个话题之前先交代一下背景最近几个月我把 Claude Code 当成了主力编码伙伴不是那种在 IDE 里开个聊天窗口的花架子而是直接在终端里跑claude让它读代码、改代码、跑测试、提交 commit一条龙那种。原本只是图个新鲜结果越用越发现决定这个工具好不好使的往往不是模型本身有多强而是你提前给它喂了什么模板——所谓 templates就是一套把固定流程、项目规范、输出格式预先定好的文本约定。这篇文章不打算复述官网文档就从我实际搭建 claude-code-templates 这套东西的经验出发聊聊模板怎么分层、怎么落地、踩了什么坑以及怎么通过切换模型让它适配不同场景。准备用或者已经在用 Claude Code 做开发的人应该能从里面找到点能直接抄作业的东西。1. 先说清楚Claude Code 里的“模板”到底是什么1.1 一个终端里的 AI 开发搭档Claude Code 是 Anthropic 官方的命令行 AI 编程工具。它跟你在网页里开个对话窗最本质的区别是它活在终端里能直接访问你的文件系统能调用命令行工具能看到测试输出和报错堆栈然后基于这些真实信息去修改代码。简单说它是一个有“动手能力”的 Agent而不是一个只能给建议的聊天机器人。它内部其实是一套循环读取你的提问决定下一步动作调用工具比如读写文件、执行 shell 命令观察结果再决定下一步。这个循环让它可以完成很多“一次性问完就能给答案”做不到的事比如跨多个文件重构一个接口或者跑完测试之后根据失败信息自动定位问题。我自己的习惯是比较复杂的需求我会直接说“你先把代码读一遍告诉我你打算怎么改再动手”这个约束如果每次都靠打字重复输入效率就很低——这正是模板要解决的问题。1.2 我眼中的模板不是一套话术而是三层结构很多人一听到“模板”就以为是几段提示词存成一个文本文件用的时候复制粘贴。这确实是最基础的玩法但实际用下来Claude Code 里的模板可以拆成三个层次每一层解决的问题都不一样。第一层是指令层。比如项目根目录下的CLAUDE.mdClaude Code 每次启动会话时都会自动读取它。你可以把技术栈、构建命令、代码风格、常见目录结构写进去相当于给 AI 一份“员工手册”。第二层是上下文注入层。Claude Code 支持用文件名的方式把外部文件内容作为上下文喂给模型。我一般会把一些比较长的规范、参考实现、历史决策记录存在项目里用到的时候用引进来。有些模板其实是一份 Markdown 文档里面记录了一个场景下的完整约束。第三层是代理模板层。在~/.claude/agents/目录下你可以用 Markdown 文件定义子代理subagent每个文件里写清楚这个代理的身份、职责、行为边界然后在对话中代理名调用它。这个已经是模板的高级玩法后面我单独展开。除了这三层Claude Code 还支持输出格式控制比如--output-format json或者自定义的格式说明。我在实际使用中更愿意把它理解成“输出模板”你告诉 AI 你想要的交付格式它就不会给你一堆流水账而是直接给适合机器处理或适合直接贴进文档的内容。理解了这几层之后你会发现所谓的 claude-code-templates本质上是在给一个很聪明但缺乏方向感的同事写一份详尽的作业指导。2. 从零装好 Claude Code顺便把 VSCode 也接上2.1 安装的两种主流方式和环境要求目前 Claude Code 最常见的安装方式有两种我两种都试过。第一种是 npm 全局安装命令很简单npm install -g anthropic-ai/claude-code。装完之后在终端里敲claude就能进入交互模式。第二种是官方提供的原生安装脚本它会下载一个独立的可执行文件不依赖 Node.js 环境。我个人的建议是如果你机器上本来就有 Node.js 18 以上的环境用 npm 方式最省事升级也方便直接重新执行npm install -g anthropic-ai/claude-code就行。如果不想为它单独装 Node.js或者对 npm 全局包有洁癖就用原生安装脚本。两条路装完之后都可以用claude --version验证是否成功。这里有个新人很容易栽的跟头在 Windows 的 PowerShell 里输claude提示“无法将 claude 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。这个报错的意思很直白就是claude命令不在你的 PATH 环境变量里。npm 全局安装的 bin 目录默认不在 PowerShell 的 PATH 里或者你刚装完没重启终端。我一般在 Windows 上会先跑npm config get prefix看全局安装路径然后手动把那个目录加到 PATH 里或者干脆用原生安装脚本它会帮你处理好 PATH。另外在 Windows 上跑 Claude Code建议使用 Windows Terminal 搭配 PowerShell 或者 Git Bash老旧的 cmd 在交互体验上真的差一个档次。还有一个和 Windows 相关的细节如果你在全新环境里启动 Claude Code 时看到类似“Claudes workspace requires the Virtual Machine Platform on Windows. Enable...”的提示不用慌这是它依赖 Windows 的虚拟化相关组件。去控制面板里找到“启用或关闭 Windows 功能”勾上“虚拟机平台”和“适用于 Linux 的 Windows 子系统”重启机器就能解决。这类环境问题大多是一次性的解决了之后基本不会再犯。2.2 登录认证和首次运行的几个坑安装只是最开始的一步真正让很多人卡住的是认证。现代版本通过claude命令启动后第一次会让你走浏览器授权流程终端里会弹出一个链接你在浏览器里完成登录授权然后把授权码贴回终端。这个体验总体算顺滑前提是你有一个可用的 Claude 账号。如果走 OAuth 登录时遇到error code token_exchange_failed这类信息通常说明 token 交换这一步出问题。我在网上看到过不少类似反馈这类问题往往和临时网络波动、系统时间不准确、或者浏览器里已有会话状态混乱有关并不是一定代表你的账号出了问题。常规做法是先检查系统时间是不是准的再换一个新的浏览器无痕窗口重新走一遍授权流程实在不行就等一段时间再试因为服务端临时的状态问题也是有可能的。另一种情况是你拿到了 API key想直接走 API 认证而不是 OAuth 登录。这时可以设置环境变量ANTHROPIC_API_KEYClaude Code 会优先使用 API key 认证。这里要注意很多人同时设置了 API key 和 OAuth 登录凭证反而会导致认证信息冲突出现 401 Unauthorized 之类的报错。我的习惯是要么走登录要么走 API key不要混着来。如果决定用 API key就确保终端环境里ANTHROPIC_API_KEY的值是正确的并且没有残留ANTHROPIC_AUTH_TOKEN这类旧变量。顺便说一句登录认证过程中如果遇到unsupported_country_region_territory的错误提示含义是当前账号所在地区不在 Anthropic 官方支持范围内。这个问题我没法替你做任何技术上的规避我的建议也很实在先认真看一下官方的支持国家和区域列表确认自己的使用场景是否合规。合规使用是底线任何绕过方式我都不推荐也不符合这篇文章的立场。如果你确实无法使用官方服务后面我会讲如何通过合法的方式把 Claude Code 接到其他兼容模型上这个反而是更稳妥的路径。2.3 VSCode 里集成 Claude Code 的配置Claude Code 的体验不仅限于终端VSCode 官方扩展也做得越来越像样。你可以在 VSCode 扩展市场搜索 “Claude Code”安装之后它会提供一个侧边栏面板你可以在面板里把项目目录添加进去然后直接对项目进行提问和操作。这个扩展本质上是复用你本地已经装好的 Claude Code CLI因此在打开 VSCode 之前请先确认命令行里的claude是可用的否则扩展会一直提示找不到 CLI。我个人的使用习惯是VSCode 侧边栏面板用于快速浏览上下文比如选中一段代码右键让它解释或者让它给当前文件写测试但真正大段的重构、跨文件修改我反而更倾向于回到终端会话里做。为什么要来回跑因为终端会话对 bash 命令的感知更强跑测试、看 git diff、读日志这种操作在终端里最自然。VSCode 扩展的优势是能高亮代码、直接把错误信息点开两边的优势其实是互补的。另外一个安全提醒这个提醒来自 Claude Code 官方也一直强调的点不要往浏览器开发者工具控制台里粘贴你不理解的代码。网上有一些教程为了让用户“解锁”某些界面功能教人往 DevTools Console 里贴一段脚本这种行为风险极高。你贴进去的代码可能直接操作你的 Cookie、本地存储甚至把你的账号信息发给第三方。我在自己账号上从来没做过这种事也强烈建议你别做。工具是拿来提升生产力的不是拿来给割韭菜的。3. 三层模板的实战设计从 CLAUDE.md 到子代理文件3.1 项目级 CLAUDE.md 怎么写才不白写CLAUDE.md是 Claude Code 在项目内的核心记忆文件每次会话启动都会自动读取。我见过很多新手把它当成摆设随便写两行“你是一个有帮助的助手”这基本等于没写。真正有价值的CLAUDE.md应该回答以下问题这个项目是干什么的、技术栈是什么、常用的构建/测试/运行命令是什么、代码结构大概怎么组织、有什么想明确的开发约定。我来给一个我自己项目里的简化示例# 项目规范 - 技术栈React TypeScript Vite - 包管理器pnpm - 开发命令pnpm dev - 构建命令pnpm build - 测试命令pnpm test - 目录约定 - src/components 放纯展示组件 - src/hooks 放自定义 hook - src/services 放 API 请求层 - 代码风格优先函数组件禁止引入未使用的依赖组件命名用 PascalCase - 开发约定 - 修改他人组件前先说明改动理由 - 所有新增公共工具函数必须写单元测试别小看这几行它们能让 Claude Code 立刻从“一个什么都懂但不知道你项目怎么跑”的通用模型变成“一个熟悉你项目结构的实习同事”。它减少的不仅是你重复解释的时间更重要的是减少猜测导致的错误。比如没有写明包管理器时Claude Code 可能随手用 npm而你的项目实际用的是 pnpm锁文件不一致改完代码拉都拉不起来。还有一个小技巧CLAUDE.md是支持嵌套的。根目录有一份子目录也可以放子目录的CLAUDE.md作用范围是那个子目录。比如在packages/backend下面可以写一套后端特有的规范Claude Code 在处理那个目录下的文件时会自动参考更具体的规则。这种“全局规范 局部细化”的结构跟公司里的团队章程、组内规范一个逻辑越贴合实际模板的价值越大。3.2 用户级模板和全局规则除了项目里的CLAUDE.mdClaude Code 还支持用户级的全局文件路径是~/.claude/CLAUDE.md。这个文件里的内容对当前用户的所有项目生效。我一般只放那些跨项目都成立的规则比如我习惯的代码风格偏好、我对 git commit message 的格式要求、我偏好的输出语言风格。举个例子如果你希望 Claude Code 在解释代码时尽量用中文、在写注释时保持简洁、在输出方案时先给结论再给细节这些都可以写进用户级文件。这是让一个 AI 工具“更像你”的关键操作。项目级文件管的是“这个项目怎么组织”用户级文件管的是“你怎么和 AI 协作”。但要注意全局规则不要写太多不然换来的是每个项目都会被一堆无关约束干扰。我见过有人把自己所有项目的技术栈都写在全局文件里结果打开一个 Java 项目模型满脑子想的还是 React 的目录划分。我的建议是全局文件最多写十条左右高度通用的规则剩下的都下沉到项目级。除了规则文件我在~/.claude/下还习惯放一些常见的“角色模板”文件。这些文件不参与自动读取而是在需要的时候用~/.claude/xxx.md手动引入。比如我有个code-review.md里面详细规定了代码审查要从哪些维度看、报告怎么排版有个refactor.md里面写着大规模重构时必须遵守的安全步骤。这类模板的好处是它们通常比较长如果每次手敲或者每次都从历史对话里翻太浪费时间而且容易漏掉关键步骤。存成文件之后用的时候一句话就能把整套规范拉进上下文。3.3 子代理模板把重复劳动包给“虚拟同事”第三层模板是我最近觉得最值回票价的部分——子代理subagents。Claude Code 允许你在~/.claude/agents/目录下放置 Markdown 文件来定义子代理每个文件就是一个虚拟角色。比如我可以定义一个测试工程师代理专门负责写测试再定义一个安全审查员代理专门审查安全相关的问题。子代理的定义文件是有固定结构的我给出一个简化示例--- name: 测试工程师 description: 专门负责编写和维护测试用例的代理擅长分析代码路径、识别边界条件。 --- 你是一个经验丰富的测试工程师。你的职责是 1. 阅读被测代码理解其输入输出约定。 2. 找出主要逻辑分支和边界条件。 3. 使用项目已有的测试框架编写测试用例。 4. 在运行测试之前先检查测试命令是否已在 CLAUDE.md 中说明。 要求 - 不要修改被测代码的业务逻辑。 - 测试用例必须覆盖正常路径、异常路径、边界值三类场景。 - 每次提交前先列出新增的测试用例清单。定义好之后在 Claude Code 对话里输入测试工程师 给这个工具函数补一下边界测试它就切换到对应角色的行为模式。比起直接在对话里说“你现在是一个测试工程师”通过子代理模板你注入的是一套完整的、写好的约束稳定性和可复用性完全不是一个级别。一个子代理文件本质上就是一套结构化的角色模板 行为准则 输出格式要求。子代理还有一个好处它可以让主模型把复杂任务分解出去。你在主对话里可以同时拉起多个子代理配合干活让一个去写实现、一个去补测试、一个去审查思路更接近真实团队协作。不过需要注意子代理本身依赖主模型做调度能力上限受底层模型影响别期待它完全是另一个独立的智能体。我的经验是子代理模板适合规范化非常明确的重复工作比如统一的代码审查流程、统一的日志埋点、统一的文档生成它们在实际工作中给我省下来的思考成本非常可观。4. 把 Claude Code 接到 DeepSeek一次换模型的完整记录4.1 为什么我会动“换模型”的念头Claude Code 默认调用 Anthropic 的 Claude 模型要正常使用你的账号和地区需要在官方支持范围内这一点前面已经提过。但很多人不知道的是Claude Code 这套终端工具本身在设计上支持通过环境变量改成其他兼容模型的接口。简单说它是玩模型接入的一个很灵活的平台。我身边有不少人通过第三方中转或者兼容接口来使用各种模型。这里我不建议去碰灰色地带我只聊一个我觉得很值得一试的合法配置把 Claude Code 接到 DeepSeek 的 Anthropic 兼容接口。DeepSeek 官方提供了与 Anthropic API 兼容的端点因此你不需要改任何代码设置几个环境变量就能让 Claude Code 用 DeepSeek 的模型来跑。为什么我会做这个切换一个很现实的原因是成本。对于大量模板化的日常任务比如生成测试用例、整理文档、简单代码解释Claude 的能力绰绰有余但按 token 计费的成本相对较高。DeepSeek 的定价更有吸引力虽然某些极其复杂的推理任务它会弱一些但对于重复度高的模板类任务它完全能胜任。另一个原因是我自己需要一份“即使官方服务不可用也能让 Claude Code 继续工作”的兜底方案。4.2 环境变量的核心三件套想让 Claude Code 走 DeepSeek 的接口核心就三个环境变量export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的DeepSeek_Key export ANTHROPIC_MODELdeepseek-chat第一个变量告诉 Claude Code 把 API 请求发到哪个地址第二个变量是认证用的 API key第三个变量指定使用哪个模型。设置好之后直接在同一个终端里运行claude它会优先读取这些环境变量绕过默认的 Anthropic 通道。在 Windows PowerShell 里写法稍微不同$env:ANTHROPIC_BASE_URL https://api.deepseek.com/anthropic $env:ANTHROPIC_AUTH_TOKEN 你的DeepSeek_Key $env:ANTHROPIC_MODEL deepseek-chat claude注意 PowerShell 里设置的环境变量只对当前窗口生效关掉窗口就没了。如果你希望长期生效可以用setx命令但要注意setx设置的是用户级环境变量新开的终端窗口才会读到。我在实际配置时更喜欢写成一个小脚本每次要用就直接 source 一下这样方便切换模型也不会污染全局环境。4.3 一个坑一个坑地排配置过程虽然只有三行环境变量但实际总会遇到问题把最常见的几种情况列一下省得大家摸索配置完成后如果启动claude报 401unauthorized: {code:invalid_api_key}先不要怀疑工具坏了最可能的原因是 key 本身不对或者 key 前面有多余空格。我犯过的低级错误是直接复制了网页里的 key结果前面多了一个不可见字符排查了半天。建议在终端里先echo $env:ANTHROPIC_AUTH_TOKEN看看实际值确认没有前后空格。还有一种是报{code:api_key_required}这个通常说明 Claude Code 根本没读到你的认证变量。可能原因是你在一个终端窗口里设置变量却在另一个窗口启动claude环境变量当然不存在。另一个原因是变量名拼写错误常见的手误是把ANTHROPIC_AUTH_TOKEN写成ANTHROPIC_API_TOKEN。这类问题本质上都是环境变量没有正确传递检查顺序永远是先确认你设置变量的终端和启动 claude 的终端是同一个再确认变量名拼写最后确认 key 内容有效。接入 DeepSeek 之后模型的实际表现会跟 Claude 有差异。我的体感是 DeepSeek 在中文语境下的理解力很好处理模板化的开发任务很稳但在一些需要非常严谨的多步推理的代码重构场景输出质量偶尔需要人工把关。所以我的用法是把两类任务分开低风险的模板类任务比如写注释、生成测试用例、整理日志默认走 DeepSeek高复杂度的架构设计、跨文件大型重构我还是切回 Claude 或者基于 DeepSeek 的更强推理模型来做。这种“按任务分流”的思路可能比单纯追求某一个模型更实际。5. 高频问题与排查技巧实录5.1 高频报错速查表用了一段时间之后我把踩过的、以及网上高频出现的报错整理成了一个速查表。不保证覆盖所有情况但遇到大多数问题都能在这里找到方向报错信息常见原因处理思路claude无法识别为 cmdlet 或命令PATH 未配置 / 未重启终端检查 npm 全局 bin 目录并加入 PATHinvalid_api_keyAPI key 错误或含不可见字符重新复制 key检查环境变量值api_key_required未设置认证变量或变量名拼错确认ANTHROPIC_AUTH_TOKEN/ANTHROPIC_API_KEYtoken_exchange_failedOAuth token 交换失败网络或会话问题检查系统时间换无痕浏览器重试unsupported_country_region_territory账号所在地区不在支持列表查看官方说明确保合规使用Windows 提示需要启用 Virtual Machine Platform虚拟化平台组件未开启在“启用或关闭 Windows 功能”里勾选相关项401 unauthorized带invalid_api_key认证信息冲突或 key 已失效检查是否同时设置了多个认证变量pre标签 /xmp标签相关困惑误把 HTML 解析问题当作 AI 报错官方并不涉及此问题多半是外部教程误导最后一行有点意思我单独解释一下。网上有些页面会显示带pre、xmp标签的内容不少人会误以为那是 Claude Code 输出的异常格式。其实这只是网页渲染问题Claude Code 在终端里输出的是纯文本压根不涉及 HTML。遇到这种情况优先看终端的原始回显别被网页教程里的渲染样式带偏了。5.2 排查思路与我的避坑习惯排查这类工具问题的通用思路我总结成一句话先区分问题发生在哪一层。是安装层、认证层、环境变量层还是模型能力层绝大多数新人报错都集中在认证和环境变量层。不要一上来就怀疑“是不是模型坏了”先检查最基础的前提——命令能不能跑、变量有没有传进去、 key 有没有生效。这个排查次序能帮你省掉大量无用功。我还有一个非常推荐的避坑习惯在任何生产项目里使用 Claude Code 之前先在会话开始明确“操作边界”。比如在 CLAUDE.md 里写明“不要直接修改 src/api 目录下的文件除非用户明确要求”或者在对话开始时说“本次会话只做代码审查不要改动任何文件”。这能避免 AI 在自由发挥时越界。模板存在的意义就是在给 AI 能力的同时也给 AI 划清楚边界。没有边界的模板写得再详细也容易跑偏。另外关于官网文档里那句“dont paste code into the DevTools console that you dont understand”我是一个字一个字看了的。这句警告值得所有用户认真对待。Claude Code 的 VSCode 扩展在安装时可能涉及开发者工具但官方从来没有要求你往控制台里粘贴任何验证代码。所有要求你贴代码到浏览器控制台的“教程”本质上都是拿你的账号安全做赌注。我在安全实践上给自己定了一条铁律任何工具都走官方渠道安装、官方文档配置任何非官方手段都不碰。6. 最后聊几个我反复在用的模板片段这一节与其说是技术总结不如说是我个人最常调用的几段模板直接拿出来供你参考。这些片段不一定适合所有人但你可以顺着这个思路去修剪自己的版本。第一个是代码审查模板我放在~/.claude/agents/code-review.md里。它的人设是“严格但不苛刻的资深 Code Reviewer”工作流程固定为先读 diff理解改动意图然后按错误风险、性能风险、可读性、测试覆盖四个维度打分最后用表格输出问题列表标明严重程度和修改建议。用了这个模板之后我每次审查的产出质量和稳定性都大幅上升不像过去临时跟 Claude 说“帮我看看代码”它给的反馈通常很散。第二个是提交信息模板。我在全局规则里要求所有 commit message 遵循“类型 简述”的格式比如fix(cart): 修复结算页库存不足时未提示。过去让我自己起 commit 名每次都要憋一会儿现在 Claude Code 读完 diff 后直接用这个模板帮我生成备选方案虽说偶尔需要改一改但至少有了一个高质量起点。第三个是“先方案后动手”模板。这个不是文件而是一句话约定“在改动任何文件之前先输出你的理解、改动点、影响范围等我确认后再动手。”我把这句话写进了项目级CLAUDE.md让它在每次会话里默认生效。用下来最大的感受是Claude Code 在“深思熟虑”模式下产生的方案往往比直接闷头改要靠谱得多而模板恰好是强制它深思熟虑的手段。聊到这里模板的价值已经不用我多说了。它本质上不是给 AI 看的咒语而是把人类团队里的默契、规范、节奏翻译成 AI 能理解的形式。如果你也在折腾 Claude Code建议从最小的CLAUDE.md开始先写五条规则用一周然后迭代。模板这东西越是用真实痛点喂出来的越贴合你的工作流。我自己在 claude-code-templates 这个文件夹里已经迭代了好几轮现在回头看最初那版明显幼稚了不少但这恰恰说明工具是死的用法才是活的。