Claude Opus 5.5 焚诀实战：Sub-agent、CLAUDE.md 与 effort 调参全链路

1. 这次“焚诀”到底更新了什么：从标题到真实能力拆解

“Claude Opus 5.5 最新焚诀发布了”这个标题，乍一看像是社区里惯用的夸张说法，但如果你最近一直在用 Claude Code 做工程化开发，就会明白它背后指向的其实是一整套围绕Claude Opus 模型、Claude Code 工具链、Sub-agent 协作机制、CLAUDE.md 项目记忆以及 effort 参数控制的能力升级。所谓“焚诀”，在圈子里通常指那种一旦掌握就能大幅提升效率的核心方法或配置组合，而不是某个单一功能。这次更新之所以被讨论得多，是因为它把模型能力、工具调用、项目上下文管理和多代理协作这几件事串成了一条更顺的链路。

我先把结论放在前面：这次变化对三类人影响最大。第一类是已经在用 Claude Code 写代码、改项目、跑脚本的开发者，他们会直接感受到 Sub-agent 调度和 effort 控制带来的差异；第二类是刚准备从零上手 Claude Code 的新手，因为安装、配置、模型接入的门槛和之前不太一样了；第三类是把 Claude Code 当成日常主力工具、依赖 CLAUDE.md 做项目记忆的团队用户，他们需要重新理解上下文注入和任务拆分的边界。如果你只是偶尔让模型写个函数，这次更新对你的体感可能没那么强，但只要你开始做多文件、多步骤、多轮迭代的工程任务，这些变化就会变得非常具体。

标题里的“焚诀”我理解成两层意思。一层是Claude Opus 5.5 本身在复杂推理和长上下文任务上的表现更稳，另一层是Claude Code 这套壳子把模型能力真正落地到了工程现场。很多人之前抱怨模型“聪明但不好用”，问题往往不在模型，而在工具链没有把任务拆清楚、上下文没喂对、effort 没调好。这次更新相当于把这几个环节的默认行为调得更合理了，尤其是 Sub-agent 的引入，让一个大任务可以被拆成多个小角色并行或串行处理，而不是所有压力都压在一个主对话里。

还有一个容易被忽略的点：热搜词里反复出现“claude code 安装”“claude code 在线升级最新版本”“windows 下怎么安装 claude code”“ubantu anzhuang claude code”这些词，说明大量用户卡在环境准备阶段。这次“焚诀”发布后，社区里讨论最多的除了模型能力，就是安装路径、权限问题、npm 前缀报错、WSL 配置、VSCode 和 PyCharm 插件接入这些非常具体的问题。所以这篇博文我不会只聊模型多强，而是会把从环境准备到 Sub-agent 实战、从 CLAUDE.md 编写到 effort 调参的完整链路拆开讲，尽量让你看完就能动手复现。

2. 核心机制拆解：Sub-agent、CLAUDE.md 与 effort 到底怎么配合

2.1 Sub-agent 不是“多开几个窗口”，而是任务角色化

很多人第一次听到 Sub-agent，会以为就是同时开几个 Claude Code 窗口，每个窗口问不同问题。实际不是。Sub-agent 的核心思路是把一个复杂任务拆成若干有明确职责的子任务，每个子任务由一个独立的代理上下文处理，最后再把结果汇总回主流程。这跟人类团队协作很像：你不会让一个人同时写前端、调后端、改数据库、写测试，而是分给不同角色，每个角色只关心自己那一块。

在 Claude Code 里，Sub-agent 的价值主要体现在三个场景。第一是代码审查与实现分离，一个代理负责写实现，另一个代理专门挑毛病，避免“自己写自己审”的盲区。第二是多文件并行修改，比如一个代理改 API 层，一个代理改 UI 层，一个代理补测试，主代理只负责协调和合并。第三是长任务分阶段处理，比如先让一个代理做需求分析，再让另一个代理做方案设计，最后让第三个代理落地代码。这样做的好处是每个子代理的上下文更干净，不容易被无关信息干扰，输出质量通常比一个超长对话里反复切换任务要高。

但 Sub-agent 也不是没有代价。最明显的问题是协调成本。如果任务拆分不合理，子代理之间信息不同步，最后合并时会出现接口对不上、命名不一致、重复实现等问题。我的经验是，拆分粒度控制在“一个子代理能在 10 到 15 分钟内独立完成并给出明确产出”比较合适。太细了调度开销大，太粗了又失去并行优势。另外，主代理必须持有全局视图，子代理只拿自己那一份上下文，否则上下文膨胀会抵消拆分带来的好处。

2.2 CLAUDE.md 是项目记忆，不是说明书

CLAUDE.md 这个文件在 Claude Code 里扮演的角色，相当于给项目写了一份“给 AI 看的入职文档”。它和普通 README 不一样，README 是给人看的，讲项目怎么用；CLAUDE.md 是给模型看的，讲这个项目里有哪些约定、哪些目录不能乱动、哪些命令必须怎么跑、代码风格是什么样。很多人第一次用 Claude Code 时觉得模型“不懂我的项目”，问题往往就出在没有认真写 CLAUDE.md。

我自己的做法是把 CLAUDE.md 分成四块。第一块是项目结构速览，用几行字说明核心目录和入口文件，让模型知道去哪里找东西。第二块是开发约定，比如包管理器用 pnpm 还是 npm、测试框架用 vitest 还是 jest、提交信息格式是什么。第三块是禁区与红线，比如不要改某个生成目录、不要动某个配置文件、不要执行某些危险命令。第四块是常用命令，比如启动开发服务器、跑测试、构建产物的具体命令。这四块写清楚，模型在后续任务里就会少犯很多低级错误。

注意：CLAUDE.md 不要写得太长。我见过有人写了上千行，结果模型每次都要花大量上下文去读它，反而挤占了真正任务的空间。控制在 100 到 200 行以内，重点突出，比面面俱到更有用。

2.3 effort 参数：控制模型“想多深”的旋钮

effort 这个词在热搜里出现，说明很多人已经注意到它了。简单说，effort 控制的是模型在回答前愿意花多少“思考预算”。effort 低的时候，模型倾向于快速给出答案，适合简单任务；effort 高的时候，模型会做更多推理、更多自我检查，适合复杂任务。这就像你让一个同事做事，你可以说“大概弄一下就行”，也可以说“这个很重要，多花点时间想清楚”。

实际使用中，我的建议是不要全程开最高 effort。原因有两个：一是高 effort 会显著增加响应时间和 token 消耗；二是对于简单任务，高 effort 并不会带来明显质量提升，反而可能让模型过度思考、把简单问题复杂化。比较合理的策略是分阶段调整：需求分析和方案设计阶段用较高 effort，代码实现阶段用中等 effort，格式调整和简单修改用低 effort。Claude Code 里可以通过配置或命令切换，具体方式取决于你使用的版本和接入方式。

3. 从零上手：安装、配置与模型接入的完整路径

3.1 环境准备：Node.js、npm 与权限问题

Claude Code 目前主要通过 npm 分发，所以第一步是确保你的机器上有合适的 Node.js 和 npm。我建议 Node.js 用 18 或 20 的 LTS 版本，太老的版本可能在依赖安装时出问题。安装完成后，用node -v和npm -v确认版本。如果你在 Windows 上，强烈建议用 WSL2 而不是原生 Windows 环境，因为很多命令行工具和脚本在 WSL 下行为更一致，社区里大量“windows 下怎么安装 claude code”的问题，最后都是切到 WSL 解决的。

安装命令本身不复杂，但权限问题是最常见的坑。热搜里有一条“claude code 报错 auto-update failed: no write permission to npm prefix”，这就是典型的 npm 全局目录权限问题。原因是 npm 默认的全局安装目录可能属于 root 或需要管理员权限，而 Claude Code 在自动更新时需要写入该目录。解决办法有两种：一是把 npm 的全局前缀改到用户目录下，比如npm config set prefix ~/.npm-global，然后把~/.npm-global/bin加到 PATH；二是用 nvm 管理 Node.js，这样全局包都装在用户目录下，天然没有权限问题。我个人更推荐 nvm 方案，干净且不容易污染系统环境。

# 以 nvm 为例，安装 Node.js 20 LTS nvm install 20 nvm use 20 node -v npm -v # 安装 Claude Code npm install -g @anthropic-ai/claude-code # 验证安装 claude --version

如果你在 Ubuntu 或其它 Linux 发行版上，流程基本一致，但要注意不要用sudo npm install -g，否则后面自动更新还是会遇到权限问题。正确做法是配置用户级 npm 前缀或用 nvm。另外，安装完成后第一次运行claude会引导你登录或配置模型接入方式，按提示操作即可。

3.2 模型接入：官方登录与第三方模型兼容

Claude Code 默认走官方模型，但社区里也有不少人想接入其它模型，比如热搜里提到的“claude code 接入 deepseek v4”“vscode 安装 claude code 调用 deepseek”。这里要说明的是，Claude Code 的架构允许通过配置切换模型端点，但具体支持程度取决于版本和配置方式。如果你只是想稳定使用，建议先用官方登录方式跑通全流程，确认工具链没问题后，再考虑接入其它模型做对比。

接入第三方模型时，核心是配置API 端点、模型名称和认证信息。不同模型的接口格式可能不完全兼容，所以需要确认 Claude Code 当前版本是否支持自定义 provider。如果支持，通常在配置文件或环境变量里设置。我的建议是：如果你主要用 Claude Code 做工程任务，优先用官方模型，因为工具调用、Sub-agent 调度这些能力和模型的配合是经过调优的；第三方模型可能在简单对话上表现不错，但在复杂工具调用场景下稳定性会有差异。

3.3 编辑器集成：VSCode 与 PyCharm 插件配置

Claude Code 可以在终端里独立使用，也可以集成到编辑器里。VSCode 和 PyCharm 都有对应的插件或集成方式。以 VSCode 为例，安装插件后需要在设置里配置 Claude Code 的可执行文件路径，确保插件能调用到终端里的claude命令。如果你在 WSL 里安装的 Claude Code，而 VSCode 跑在 Windows 侧，需要确保 VSCode 连接到 WSL 远程环境，否则插件找不到命令。

PyCharm 的配置类似，核心是让 IDE 知道 Claude Code 在哪里，以及用哪个工作目录作为项目根。这里有个细节：工作目录很重要，因为 CLAUDE.md 的读取、文件索引、Sub-agent 的任务范围都跟工作目录有关。如果你在 IDE 里打开的项目根目录和终端里运行 Claude Code 的目录不一致，模型可能会找不到 CLAUDE.md 或索引到错误的文件。我一般建议在项目根目录下打开终端，再启动 Claude Code，这样上下文最干净。

4. 实操全流程：用 Sub-agent 完成一个多文件改造任务

4.1 任务设定与 CLAUDE.md 准备

假设我们要做一个真实场景：一个 Node.js 后端项目，需要把现有的 REST API 从旧版路由写法迁移到新版框架写法，同时补上单元测试和接口文档。这个任务涉及多个文件、多个层次，适合用 Sub-agent 拆分。第一步是写好 CLAUDE.md，让模型知道项目结构、测试命令和代码约定。

# CLAUDE.md ## 项目结构 - src/routes/ 路由定义 - src/controllers/ 业务逻辑 - src/services/ 数据访问 - tests/ 单元测试 - docs/ 接口文档 ## 开发约定 - 包管理器：pnpm - 测试框架：vitest - 代码风格：ESLint + Prettier - 提交信息：conventional commits ## 常用命令 - 安装依赖：pnpm install - 跑测试：pnpm test - 启动开发：pnpm dev ## 禁区 - 不要修改 src/generated/ 下的文件 - 不要改动 .env 和 CI 配置

这份 CLAUDE.md 不长，但把关键信息都覆盖了。模型在后续任务里会优先读它，减少来回确认的成本。

4.2 主代理拆解任务并派发子代理

接下来在主对话里描述任务，让主代理拆解。我的提示词大概是这样的：

请把以下任务拆解成适合 Sub-agent 执行的子任务，并说明每个子任务的职责、输入、输出和验收标准。 任务：把 src/routes/ 下的旧版路由迁移到新版框架写法，补上对应单元测试，并更新 docs/ 下的接口文档。 要求： 1. 不要一次性改所有文件，按模块分批。 2. 每个子任务完成后给出变更文件列表和测试结果。 3. 主代理负责最终合并和一致性检查。

主代理通常会拆成三到四个子任务：路由迁移、控制器适配、测试补充、文档更新。每个子任务可以分配给一个 Sub-agent。这里的关键是验收标准要明确，比如“迁移后所有旧路由测试通过”“新测试覆盖率达到 80%”“文档中的请求示例与实际接口一致”。没有验收标准，子代理的输出很难判断是否合格。

4.3 子代理执行与结果汇总

子代理执行时，每个代理只拿到自己那一部分上下文。比如路由迁移代理只需要知道旧路由文件、新框架的写法示例和 CLAUDE.md 里的约定；测试代理只需要知道迁移后的路由和测试框架用法。这样做的好处是每个代理的上下文都很聚焦，不容易被无关信息干扰。

执行过程中，我建议主代理定期做一致性检查。比如路由迁移代理改了 URL 命名，测试代理还在用旧命名，最后合并就会失败。解决办法是在派发任务时就把接口契约固定下来，比如“所有路由路径保持不变，只改内部实现”。如果必须改路径，那就要先更新契约，再让所有子代理基于新契约工作。

子任务 1：迁移 src/routes/user.js 到新版框架写法 - 输入：旧文件内容、新框架示例、CLAUDE.md - 输出：迁移后的文件、变更说明 - 验收：文件语法正确，路由路径不变，导出方式符合新框架要求 子任务 2：为迁移后的 user 路由补充单元测试 - 输入：迁移后的路由文件、现有测试示例、测试命令 - 输出：新增测试文件、测试运行结果 - 验收：所有新增测试通过，覆盖主要分支

4.4 effort 调参与执行节奏控制

在这个流程里，effort 的调整很关键。任务拆解阶段我会用较高 effort，因为拆得好不好直接决定后续效率。子代理执行阶段用中等 effort，保证质量的同时控制时间。最后的合并和格式检查用低 effort，因为这部分主要是机械性工作。实际用下来，这种分阶段调参比全程高 effort 快不少，而且质量没有明显下降。

还有一个实操技巧：不要让子代理一次改太多文件。我试过让一个子代理一次性迁移十个路由文件，结果它在中途丢失了部分上下文，后面几个文件的写法跟前面对不上。后来改成每个子代理最多处理三到四个文件，质量就稳定多了。这跟人类工作一样，任务太大容易疲劳出错，拆小一点反而更快。

5. 常见问题与排查技巧实录

5.1 安装与升级类问题速查

这张表里的问题我几乎都遇到过，尤其是权限那条。很多人第一次装的时候用sudo，当时能装上，但后面自动更新就报错。根因是 npm 全局目录属于 root，普通用户没写权限。换成 nvm 之后，所有全局包都在用户目录下，这个问题就彻底消失了。

5.2 Sub-agent 协作中的典型坑

Sub-agent 用起来很爽，但坑也不少。第一个坑是上下文不同步。主代理改了某个接口，子代理不知道，还在按旧接口写。解决办法是主代理在派发任务时把最新契约写进子任务描述里，不要假设子代理知道主对话里发生了什么。第二个坑是重复实现。两个子代理都以为某个工具函数不存在，各自写了一个，最后合并时冲突。解决办法是在 CLAUDE.md 里维护一份公共工具清单，或者在派发任务时明确“不要新建工具函数，优先复用 src/utils/ 下的现有实现”。

第三个坑是验收标准模糊。比如“优化代码质量”这种描述，子代理不知道做到什么程度算完成。我后来改成“消除所有 ESLint 报错，函数复杂度不超过 10，补充缺失的类型注解”，这样输出就稳定多了。第四个坑是effort 全程开太高，导致每个子任务都很慢，整体效率反而下降。分阶段调参之后，整体耗时大概能降三成左右。

5.3 CLAUDE.md 编写中的常见误区

CLAUDE.md 写得好不好，直接决定模型在你项目里的表现。我见过几种典型误区。第一种是写成 README 的复制粘贴，讲了一堆项目背景和业务价值，但对模型真正有用的目录结构、命令、约定反而没写。第二种是写得太细，把每个函数的实现细节都写进去，结果模型每次都要读大量无关信息。第三种是从不更新，项目结构变了、命令变了，CLAUDE.md 还是旧的，模型按旧信息操作就会出错。

我的建议是把 CLAUDE.md 当成活文档，每次项目结构或约定有变化就顺手更新。内容上遵循“模型需要知道什么就写什么”的原则，不需要面面俱到。另外，可以在 CLAUDE.md 里加一条“如果发现文档与实际不符，请先指出再继续”，这样模型遇到不一致时会主动提醒你，而不是默默按错误信息执行。

提示：如果你在团队里用 Claude Code，建议把 CLAUDE.md 纳入代码审查范围。新人加入时，这份文件也是快速了解项目约定的好材料。

6. 我个人在实际操作中的几点体会

用 Claude Code 配合 Sub-agent 和 CLAUDE.md 做工程任务，最深的体会是工具能力越强，对使用者的任务拆解能力要求越高。以前模型弱的时候，你随便问它随便答，错了也无所谓；现在模型能真正改你的代码、跑你的测试，你就必须把任务边界、验收标准、上下文范围想清楚。否则它越能干，捅的篓子可能越大。

另一个体会是effort 不是越高越好，而是越合适越好。我早期也喜欢全程拉满，觉得这样质量最高，后来发现很多简单任务根本不需要那么多思考预算，拉满反而慢且贵。现在我的习惯是：拆任务和做方案时拉高，执行时中等，收尾时降低。这套节奏用下来，整体效率和质量的平衡最好。

最后分享一个小技巧：每次大任务开始前，先让模型复述一遍它理解的任务目标和约束。这一步花不了多少时间，但能提前发现理解偏差。我遇到过好几次，模型复述时把某个约束理解反了，如果直接开干，后面就要花更多时间返工。让它先复述，确认无误再动手，整体反而更快。这个习惯在 Sub-agent 场景下尤其重要，因为子代理之间不会自动对齐理解，主代理复述确认后，再把确认过的描述派发给子代理，一致性会好很多。