1. 这次“焚诀”到底更新了什么：从标题拆解到核心能力全景

“焚诀”这个词在圈子里流传有一阵子了，它其实是对 Claude Opus 系列一次大版本能力跃迁的戏称——意思是这套模型组合拳打出来，像焚诀一样把旧的工作流烧了个干净。这次 Opus 5.5 的发布，配合 Claude Code 这个终端里的智能体工具，真正让“一个人顶一个小组”这件事从口号变成了可复现的日常。我先把结论摆前面：这次更新最值得关注的三块，分别是 Sub-agent 多智能体协作机制 、 CLAUDE.md 项目记忆文件体系 ，以及 effort 参数对推理深度的精细控制 。这三样东西凑在一起，才构成了所谓“焚诀”的完整形态。

先说 Sub-agent。过去的 Claude Code 更像一个单线程的助手，你给它一个任务，它从头干到尾，中间遇到需要查资料、跑测试、改配置的环节，都是它一个人扛。问题是上下文窗口再大也架不住这么造，干到后面它就开始“忘事”，前面定的规范后面就违反了。Sub-agent 的思路是把一个大任务拆给多个专职的小智能体，每个小智能体只负责自己那一块，主智能体负责调度和汇总。这就像你带团队，不会让一个人既写前端又调数据库还兼测试，而是分给不同的人，各自专注。

再说 CLAUDE.md。这个文件本质上是给项目写的一份“交接文档”，放在项目根目录，Claude Code 每次启动都会读它。里面写清楚这个项目是干什么的、代码规范是什么、常用命令有哪些、哪些目录不能碰。有了它，你就不用每次开新会话都重新解释一遍背景，模型自己就知道该守什么规矩。我实测下来，一个写得好的 CLAUDE.md 能把重复沟通成本砍掉一大半。

最后是 effort 参数。这个参数控制模型在回答前“想多久”。effort 调高，它会花更多时间做推理链，适合复杂架构设计、疑难 bug 排查；effort 调低，响应快、省 token，适合改个变量名、写个注释这种小事。很多人不知道这个参数，结果要么是简单任务等半天，要么是复杂任务它想得太浅给出错误方案。把 effort 用对，是这次“焚诀”能不能发挥威力的关键。

这三样东西的组合逻辑是这样的：CLAUDE.md 定规矩，Sub-agent 分活干，effort 控制每件事投入的脑力。三者配合，才能让 Claude Code 从一个“能聊天的终端”变成“能交付项目的工程搭档”。下面我会把每一块拆开讲透，包括怎么配、怎么调、踩过哪些坑。

2. Sub-agent 多智能体协作：把一个人的活拆成一个组来干

2.1 为什么单智能体干大项目会崩

先讲清楚问题，不然你不知道 Sub-agent 到底解决了什么。单智能体干大项目，核心矛盾是 上下文污染 。你让它先读十个文件理解项目结构，再改三个模块，再跑测试，再根据测试结果修 bug。这一套下来，上下文里塞满了文件内容、报错信息、中间推理过程。等到它要改第三个模块的时候，前面读的文件内容已经把它对“项目规范”的记忆挤到边缘了，它就开始瞎改——变量命名不统一了，错误处理漏了，甚至把你明确说过不要动的文件给改了。

这不是模型笨，是上下文窗口的物理限制。再大的窗口，信息密度一高，注意力就会被稀释。Sub-agent 的解法很直接： 每个子智能体只带自己需要的那部分上下文 。查资料的只带搜索需求，写代码的只带相关文件和规范，跑测试的只带测试命令和预期结果。主智能体不把所有细节都吞进来，它只负责“谁该干什么”和“干完了汇总”。

2.2 Sub-agent 的配置方式与角色划分

Claude Code 里配置 Sub-agent 通常是在项目根目录建一个 .claude/agents/ 目录，里面每个子智能体一个配置文件。配置内容一般包括：这个子智能体的名字、它负责什么、它能用哪些工具、它的系统提示词是什么。我拿一个典型的前后端项目举例，通常会分这么几个角色：

• researcher ：负责查文档、搜代码库、找相关实现。工具权限只给读取和搜索，不给写入，防止它乱改东西。
• coder ：负责写和改代码。给它文件读写权限，但系统提示词里明确写清楚代码规范，并且要求它改完必须说明改了什么。
• tester ：负责跑测试、分析失败原因。给它命令执行权限，但不给文件写入权限，它只能报告问题不能自己修。
• reviewer ：负责审查 coder 的产出。给它读取权限，让它对照 CLAUDE.md 里的规范逐条检查。

主智能体接到任务后，先判断这个任务需要哪几个角色，然后按顺序或并行调度。比如“给用户模块加一个导出功能”，主智能体可能会先叫 researcher 去查现有的导出相关代码，再叫 coder 基于查到的结果写实现，再叫 tester 跑测试，最后叫 reviewer 审一遍。

注意：子智能体的系统提示词一定要写“边界”。我踩过的坑是 researcher 因为提示词没写清楚，跑去改了配置文件，结果把项目搞崩了。后来我在每个子智能体的提示词开头都加一句“你只负责 X，不要做任何超出 X 范围的操作”，这类事故就再没出现过。

2.3 主智能体的调度逻辑与实操心得

主智能体的调度不是固定流程，它根据任务动态决定。这里有个经验： 任务描述越具体，调度越准 。你如果说“优化一下项目”，主智能体可能叫一堆子智能体乱转；你如果说“把 user 模块的查询接口从同步改成异步，保持现有返回结构不变”，它就能精准地只叫 coder 和 tester。

另外，Sub-agent 之间默认是不共享上下文的，这是好事也是坏事。好事是防止污染，坏事是 coder 不知道 researcher 查到了什么。解法是主智能体在调度时把上一个子智能体的输出作为输入传给下一个。这个传递过程是自动的，但你要在任务描述里明确“基于上一步的结果继续”，否则主智能体可能让 coder 从零开始。

我实测下来，Sub-agent 模式最适合的是 中等规模、模块边界清晰 的项目。如果项目本身耦合极重，改一个地方牵动全身，那子智能体之间的信息传递成本会很高，反而不如单智能体一把梭。判断标准很简单：如果你的项目能拆成几个相对独立的模块，Sub-agent 就值得上；如果是一坨面条代码，先把代码理清楚再说。

3. CLAUDE.md 项目记忆文件：让模型每次开局就知道规矩

3.1 CLAUDE.md 到底该写什么

CLAUDE.md 不是随便写写的 README，它是给模型看的“项目宪法”。我见过太多人把它写成项目介绍，结果模型读完还是不知道该守什么规矩。一份有效的 CLAUDE.md 应该包含这几块：

• 项目定位 ：一句话说清楚这个项目是干什么的，技术栈是什么。比如“这是一个基于 Node.js 的电商后端，用 PostgreSQL 做存储，部署在容器里”。
• 代码规范 ：命名约定、目录结构约定、错误处理约定。比如“所有异步函数必须用 async/await，禁止回调；错误统一用 AppError 类抛出”。
• 常用命令 ：怎么装依赖、怎么跑测试、怎么启动开发环境。模型需要这些来验证自己的改动。
• 禁区 ：哪些文件不能动、哪些操作不能做。比如“不要修改 migrations 目录下的历史文件；不要直接改 package.json 的依赖版本”。
• 当前任务上下文 ：如果这个项目正在做某个大功能，可以在这里写清楚当前进度和下一步计划。

我自己的习惯是把 CLAUDE.md 控制在 200 行以内。太长了模型读起来费劲，而且重点会被淹没。如果内容确实多，就拆成 CLAUDE.md 加几个引用文件，CLAUDE.md 里只放最核心的规矩和指向其他文件的链接。

3.2 怎么写才能让模型真正遵守

写规矩和让模型守规矩是两回事。我总结了几条让 CLAUDE.md 真正生效的经验：

第一， 用命令式而不是描述式 。写“禁止使用 var”比写“项目倾向于使用 let 和 const”有效得多。模型对“禁止”“必须”“不要”这类词的敏感度远高于“倾向于”“建议”。

第二， 给正例也给反例 。光说“错误处理要统一”模型不知道你指什么，加上“正确写法是 try/catch 里抛 AppError，错误写法是直接 console.log 然后 return null”，它就清楚了。

第三， 把最重要的规矩放最前面 。模型的注意力是前重后轻的，开头的内容权重最高。如果你有一条绝对不能违反的规矩，放在第一段。

第四， 定期更新 。项目在变，规矩也在变。我一般每完成一个大功能就回头看一眼 CLAUDE.md，把过时的规矩删掉，把新踩的坑加进去。这个文件是活的，不是写完就扔那儿的。

提示：CLAUDE.md 里可以写“如果你不确定某件事是否符合规范，先问我再动手”。这句话能挡掉很多模型自作主张的改动。我加上这句之后，模型主动询问的频率明显上升，返工率下降了不少。

3.3 CLAUDE.md 与 Sub-agent 的配合

CLAUDE.md 和 Sub-agent 是互补的。CLAUDE.md 定的是全局规矩，所有子智能体都要遵守；Sub-agent 的配置里定的是角色专属规矩，比如 coder 要遵守代码规范，tester 要遵守测试规范。主智能体在调度子智能体时，会把 CLAUDE.md 的内容作为基础上下文传给每个子智能体，确保大家守的是同一套规矩。

这里有个细节：子智能体的系统提示词里不要再重复 CLAUDE.md 的内容，否则上下文会冗余。正确做法是子智能体提示词里写“遵守项目根目录 CLAUDE.md 中的所有规范”，然后主智能体负责把 CLAUDE.md 注入进去。这样规矩只有一份，改的时候也只改一处。

我踩过的坑是早期把规范同时写在 CLAUDE.md 和子智能体提示词里，结果两边不一致，模型不知道该听谁的，行为变得很混乱。后来统一到 CLAUDE.md 一处，问题就解决了。

4. effort 参数：控制模型“想多久”的油门

4.1 effort 参数的取值与影响

effort 是 Claude Code 里控制推理深度的参数，取值一般从 low 到 high 分几档。它的作用机制是控制模型在给出最终回答前，内部推理链的长度。effort 越高，模型会花更多 token 在“思考”上，把问题的各个角度都过一遍，再给答案；effort 越低，模型倾向于直接给答案，推理链短。

这个参数的影响是双向的。高 effort 的代价是响应慢、token 消耗大，但复杂问题的正确率明显更高。低 effort 的代价是可能想得不够周全，但简单任务上速度快、成本低。关键是根据任务类型选对档位。

我实测下来，不同任务类型的推荐档位是这样的：

任务类型	推荐 effort	理由
改变量名、写注释、格式化	low	不需要推理，直接改就行
写单个函数、修简单 bug	medium	需要一点推理但不多
设计模块架构、排查疑难 bug	high	需要多角度权衡，推理链要长
重构大段代码、跨模块改动	high	牵一发动全身，必须想周全

4.2 怎么在实操中调 effort

在 Claude Code 里调 effort 一般有两种方式：一种是在启动时通过命令行参数指定，一种是在会话中动态切换。我习惯的做法是 默认用 medium，遇到复杂任务手动切 high 。这样大部分日常操作不会太慢，遇到硬骨头再给它加脑力。

这里有个经验： effort 不是越高越好 。我试过把所有任务都设成 high，结果改个变量名它也要想半天，等得人心焦，而且 token 消耗翻了好几倍。后来改成按任务类型切换，效率明显提升。判断标准很简单：如果这个任务你自己做的时候需要停下来想一想，那就用 high；如果是不用过脑子直接干的，就用 low 或 medium。

还有一个细节：effort 和 Sub-agent 配合时，可以给不同子智能体设不同的 effort。比如 researcher 用 medium 就够了，coder 用 high，tester 用 medium。这样整体效率最优。配置方式是在子智能体的配置文件里单独指定 effort，主智能体调度时会按各自的设置执行。

注意：effort 调高之后，模型的输出会变长，因为它会把推理过程也带出来。如果你只想要结果不想要过程，可以在提示词里写“只给最终结果，不要展示推理过程”。但我的建议是复杂任务还是让它展示推理过程，这样你能看出它哪里想错了，方便纠正。

4.3 effort 与成本控制的平衡

effort 直接关系到 token 消耗，而 token 就是钱。我算过一笔账：同一个复杂任务，high effort 比 medium effort 多消耗大概 2 到 3 倍的 token，但正确率能从七成提到九成以上。对于生产环境的代码改动，这个投入是值得的，因为返工的成本更高。对于实验性的探索，medium 就够了，错了重来也不心疼。

我的策略是 把 effort 当成预算来管 。每天开始工作前，先想清楚今天要干几件复杂任务，这些任务预留 high effort 的预算；剩下的日常小改用 medium 或 low。这样既保证了关键任务的质量，又不会在琐事上烧钱。

另外，Sub-agent 模式本身也是一种成本控制手段。因为每个子智能体只带自己需要的上下文，总体 token 消耗比单智能体扛全部要低。配合 effort 的精细控制，整体成本能压下来不少。

5. 从零上手：Claude Code 的安装与项目接入实操

5.1 安装前的环境准备

Claude Code 是跑在终端里的工具，对系统环境有基本要求。我按不同系统分别说。

macOS 和 Linux ：需要 Node.js 18 以上版本。装 Node 最省事的方式是用 nvm，它能让你在不同 Node 版本之间切换，避免版本冲突。装完 Node 之后，用 npm 全局安装 Claude Code 的命令行工具。这里有个常见坑：如果 npm 的全局目录没有写权限，安装会报 “no write permission to npm prefix” 这个错。解法是先把 npm 的全局目录改到你用户目录下，再装。

Windows ：官方推荐用 WSL，也就是在 Windows 里跑一个 Linux 子系统。直接在 Windows 原生环境装也能跑，但路径处理和命令兼容性会有小问题，WSL 更稳。WSL 装好之后，里面的操作和 Linux 一样。如果你不想用 WSL，那就在 PowerShell 里操作，但要注意路径分隔符和权限问题。

提示：安装之前先确认你的 Node 版本，用 node -v 查一下。低于 18 的话先升级 Node，否则 Claude Code 跑不起来。这个坑我见过太多人踩，装了半天发现是 Node 版本太老。

5.2 安装步骤与验证

安装本身不复杂，关键是装完要验证。步骤大致是：先确认 Node 和 npm 可用，然后用 npm 全局安装 Claude Code 的命令行包，装完之后用版本命令验证是否成功。如果验证命令能输出版本号，说明装好了。

装好之后第一次运行，它会引导你做登录或者配置。这里要说明的是，Claude Code 支持接入不同的模型后端，你可以用官方提供的，也可以配置成接入其他兼容的模型服务。配置方式一般是通过环境变量或者配置文件指定 API 地址和密钥。具体怎么配取决于你用的模型服务，这里不展开，但思路是通用的：找到配置文件，填入服务地址和凭证，然后验证连通性。

验证连通性的方法很简单：启动 Claude Code，问它一个简单问题，看它能不能正常回答。如果报连接错误，先检查网络和配置，再检查密钥是否有效。这一步过了，后面就顺了。

5.3 在 VS Code 里配置 Claude Code

很多人习惯在 VS Code 里干活，Claude Code 也能集成进去。配置方式一般是在 VS Code 的设置里找到终端相关配置，把 Claude Code 的启动命令配进去，或者直接用 VS Code 的集成终端手动启动。我自己的做法是开一个专门的终端面板跑 Claude Code，代码编辑在另一个面板，这样互不干扰。

如果你想让 Claude Code 直接读取你当前打开的项目，就在项目根目录启动它。它会自动把当前目录作为工作目录，读取里面的 CLAUDE.md 和项目文件。这样你就不用来回切换目录了。

注意：在 VS Code 里跑 Claude Code 时，注意终端的默认 shell 要和你的系统匹配。Windows 上如果默认 shell 是 PowerShell 但你在 WSL 里装的 Claude Code，就会找不到命令。解法是把 VS Code 的默认终端改成 WSL，或者在 WSL 终端里手动启动。

5.4 项目接入的完整流程

把 Claude Code 接入一个现有项目，我通常按这个流程走：

1. 在项目根目录启动 Claude Code ，让它先读一遍项目结构。
2. 写 CLAUDE.md ，把项目定位、规范、命令、禁区都写进去。第一版不用完美，先有个框架。
3. 配置 Sub-agent ，根据项目特点划分角色。小项目两三个角色就够，大项目可以多分几个。
4. 跑一个简单任务试水 ，比如让它改一个明显的 bug 或者加一个简单功能，观察它的行为是否符合预期。
5. 根据试水结果调整 CLAUDE.md 和 Sub-agent 配置 ，把发现的问题补进规矩里。
6. 正式投入使用 ，从简单任务开始，逐步过渡到复杂任务。

这个流程的核心是 先小步验证再放大 。我见过有人一上来就让 Claude Code 重构整个项目，结果模型理解偏差，改出一堆问题，还得手动回滚。先跑小任务，你才能知道它在你的项目里表现如何，规矩定得对不对。

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

6.1 安装与配置类问题

问题一：安装时报 “no write permission to npm prefix” 。这是 npm 全局目录权限问题。解法是查看当前 npm 全局目录位置，然后把它改到你用户目录下有写权限的地方，再重新安装。改完之后记得把新的全局目录加到 PATH 里，否则命令找不到。

问题二：Windows 下找不到命令 。如果你在 WSL 里装的 Claude Code，但在 PowerShell 里敲命令，肯定找不到。解法是要么在 WSL 终端里操作，要么把 VS Code 的默认终端改成 WSL。另外检查一下 WSL 里的 PATH 是否包含 npm 全局目录。

问题三：启动后连不上模型服务 。先检查配置文件里的服务地址和密钥是否正确，再检查网络是否通。如果用的是自建服务，确认服务本身在运行。这一步排查顺序是先配置后网络，因为配置错误比网络问题更常见。

问题四：自动更新失败 。Claude Code 有自动更新机制，如果更新时报权限错误，通常是安装目录没有写权限。解法是手动更新，或者把安装目录权限改对。我一般关掉自动更新，手动控制更新时机，避免干活干到一半它自己更新重启。

6.2 使用过程中的典型问题

问题五：模型不遵守 CLAUDE.md 里的规矩 。先检查规矩是不是写得太模糊，把“倾向于”改成“必须”，把描述改成命令式。再检查规矩是不是放得太靠后，把最重要的提到最前面。如果还不行，就在子智能体提示词里再强调一遍关键规矩。

问题六：Sub-agent 之间信息传递丢失 。这是主智能体调度时没把上一步输出传下去。解法是在任务描述里明确写“基于上一步的结果继续”，并且在子智能体配置里要求它输出结构化的结果，方便传递。

问题七：effort 调高后响应太慢 。检查是不是把简单任务也设成了 high。按任务类型分档，简单任务用 low 或 medium。另外可以给不同子智能体设不同 effort，避免整体都慢。

问题八：模型改动了不该改的文件 。这是禁区没写清楚。在 CLAUDE.md 里明确列出不能动的目录和文件，并且在子智能体提示词里也强调一遍。我还会在项目里用只读权限保护关键文件，从物理上防止误改。

6.3 独家避坑技巧汇总

坑点	表现	解法
上下文污染	模型干到后面忘了前面的规矩	用 Sub-agent 拆分任务，每个子智能体只带必要上下文
规矩不生效	模型无视 CLAUDE.md	用命令式写法，重要规矩放最前，子智能体提示词再强调
effort 浪费	简单任务等半天	按任务类型分档，子智能体单独设 effort
信息传递丢失	子智能体各干各的	主智能体调度时显式传递上一步输出
误改关键文件	模型动了不该动的东西	CLAUDE.md 写禁区，物理上设只读权限
安装权限错误	npm 全局目录没写权限	改 npm 全局目录到用户目录，更新 PATH
自动更新打断工作	干活中途自动更新	关掉自动更新，手动控制更新时机

这些坑我基本都踩过一遍，每一条都是真金白银换来的经验。尤其是上下文污染和规矩不生效这两条，早期让我返工了无数次。后来把 Sub-agent 和 CLAUDE.md 配合起来用，情况才好转。

7. 把“焚诀”用出威力的几个实战建议

7.1 从小项目开始练手

别一上来就拿核心项目试。找一个边缘的、不那么重要的项目，把 Claude Code 的整套流程跑一遍。写 CLAUDE.md、配 Sub-agent、调 effort，全流程走通，看看哪里卡壳。这个过程大概需要一两天，但能帮你建立起对这套工具的直觉。等你知道了它在什么情况下靠谱、什么情况下会翻车，再往核心项目上迁移。

我自己的第一个练手项目是一个内部用的小工具，代码量不大，改坏了也不影响生产。就是在这个小项目上，我把 CLAUDE.md 的写法、Sub-agent 的划分、effort 的档位都摸清楚了。后来上核心项目时，基本没出大问题。

7.2 把规矩当成代码来维护

CLAUDE.md 和 Sub-agent 配置不是写完就完事的，它们需要像代码一样维护。每次模型犯了错，就想想是哪条规矩没写清楚，补进去。每次项目结构变了，就更新对应的配置。我一般会在每次迭代结束时花十分钟过一遍这些配置文件，把过时的删掉，把新踩的坑加上。

这个习惯的价值在于，它让模型的表现在长期是 收敛 的，而不是随机波动。没有维护的规矩，模型今天守明天忘；有维护的规矩，模型会越来越懂你的项目。

7.3 人始终在环里

不管 Sub-agent 多智能，effort 多高，人始终要在环里。我的做法是 关键改动必须人工 review 。模型改完代码，我会看它的改动说明，对照 diff 检查。Sub-agent 的 reviewer 角色能挡掉一部分问题，但它也是模型，也会漏。最终把关的还是人。

这不是不信任工具，而是工程纪律。模型再强，它不知道你的业务上下文里那些没写进文档的隐含约束。人 review 的价值就在于补上这一层。我实测下来，有人 review 的流程，最终交付质量比全自动流程高一个档次。

7.4 持续关注版本更新

Claude Code 和 Opus 系列更新很快，每隔一段时间就有新能力。我的习惯是每次更新后先看更新日志，搞清楚新增了什么、改了什么，然后在小项目上试一遍新功能。这次 Opus 5.5 的 Sub-agent 和 effort 就是更新里最值得关注的两块，我第一时间就在练手项目上试了，确认稳定之后才迁移到核心项目。

关注更新不是为了追新，而是为了不错过能提升效率的能力。有些更新看起来小，用起来能省不少事。比如某次更新优化了 CLAUDE.md 的读取逻辑，模型对规矩的遵守度明显提升，这种更新如果错过了就亏了。

最后分享一个我自己的小习惯：我会给每个项目建一个 notes.md ，记录这个项目里 Claude Code 的表现——哪些任务它干得好，哪些任务它翻过车，用了什么配置。时间长了，这份笔记就成了我调教模型的“错题本”，下次遇到类似任务，翻一翻就知道该怎么配。这个习惯看起来笨，但实测下来，它比任何教程都管用，因为它是针对你自己的项目、你自己的代码风格总结出来的。