1. 这次“焚诀”到底更新了什么从标题拆解到核心变化“焚诀”这个词在圈子里其实是个戏称指的是那种一旦用上就回不去、算力烧得心疼但产出质量高到离谱的配置组合。这次 Claude Opus 5.5 被冠上“最新焚诀”核心不是模型本身跑分涨了多少而是围绕 Claude Code 这套命令行智能体工作流把CLAUDE.md 项目记忆、Sub-agent 子代理编排、effort 推理强度控制这三件事捏成了一个可复用的组合拳。我第一时间在自己的两个中型项目里跑了一遍下面把拆解过程、配置细节和踩坑记录完整写出来。先说清楚这套东西是什么、能干什么。Claude Code 是一个跑在终端里的智能体工具它能读你本地的代码库、执行命令、改文件、跑测试而 CLAUDE.md 是放在项目根目录的一份“给智能体的说明书”告诉它这个项目的技术栈、目录约定、禁止事项。Sub-agent 是主代理派生出来的专职小代理比如一个专门查文档、一个专门写测试、一个专门做代码审查各自有独立的上下文窗口。effort 则是控制模型“想多久”的档位从低到高对应不同的推理深度和 token 消耗。这三者组合起来解决的是同一个老问题大模型写代码时上下文爆炸、任务跑偏、质量不稳定。适合谁来参考如果你已经在用 Claude Code 但只是把它当高级补全工具那这套配置能让你的产出质量上一个台阶如果你还没上手建议先按后面的安装章节把环境跑通再回来看编排部分。我尽量把每一步的参数选择理由都写清楚不堆术语让刚接触的人也能照着抄。2. 环境准备Claude Code 安装与版本升级的完整路径2.1 安装前的依赖检查与常见报错预防Claude Code 本质是一个 Node.js 命令行工具所以第一步是确认 Node 环境。我实测下来Node 18 LTS 以上都能跑但推荐 20.x因为部分依赖在新版本上编译更顺。检查命令很简单node -v npm -v如果版本低于 18先去 Node 官网装 LTS 版本。这里有个新手常踩的坑用系统包管理器装的 Node 往往版本偏旧而且 npm 全局目录权限容易出问题。我建议直接用官方安装包或者 nvm 管理版本省得后面遇到权限报错。安装命令本身不复杂npm install -g anthropic-ai/claude-code但这一步在 Windows 上经常翻车。如果你在 Windows 下直接跑可能会遇到auto-update failed: no write permission to npm prefix这类报错原因是 npm 全局目录没有写权限。解决办法有两个一是用管理员权限打开终端重装二是改 npm 的全局前缀到一个你有权限的目录npm config set prefix C:\Users\你的用户名\npm-global然后把C:\Users\你的用户名\npm-global加到系统 PATH 里。我个人更推荐在 Windows 上用 WSL因为 Claude Code 的很多能力依赖类 Unix 环境WSL 下体验顺畅得多。WSL 里就按 Ubuntu 的流程走先sudo apt update再装 Node最后全局安装基本不会遇到权限问题。2.2 在线升级与版本锁定策略Claude Code 更新很频繁官方支持在线升级。升级命令npm update -g anthropic-ai/claude-code或者直接重装最新版。这里我要提醒一句不要盲目追最新版。我有一次在项目交付前一天升级结果新版对某个配置项的解析变了导致 Sub-agent 编排直接失效。后来我养成了习惯升级前先看 release notes升级后在测试分支跑一遍核心流程确认没问题再合并到主分支。如果你需要锁定版本可以指定版本号安装npm install -g anthropic-ai/claude-code1.x.x版本号去 npm 页面查。锁定版本的好处是团队协作时大家环境一致不会出现“你那边能跑我这边报错”的情况。我现在的做法是项目根目录放一个.nvmrc和一个package.json记录推荐版本新人入职照着装就行。2.3 首次启动与登录方式选择安装完成后在项目目录下直接输入claude就能启动。首次启动会引导你完成认证。这里涉及一个很多人关心的问题能不能不登录、用其他模型从工具设计上讲Claude Code 是围绕自家模型能力深度优化的Sub-agent 编排、effort 控制这些特性都依赖特定模型的接口。如果你想接入其他模型社区确实有一些桥接方案但实测下来在工具调用、长上下文处理上会有明显折扣尤其是 Sub-agent 的上下文隔离机制容易出问题。我的建议是如果你要正经用这套“焚诀”就用官方支持的模型别为了省事牺牲稳定性。登录流程跟着提示走就行浏览器授权完成后终端会显示成功。如果遇到登录卡住先检查网络代理设置再确认系统时间是否准确时间偏差过大会导致认证失败。3. CLAUDE.md 项目记忆文件让智能体真正懂你的项目3.1 CLAUDE.md 的定位与最小可用结构CLAUDE.md 是整个工作流的地基。你可以把它理解成“给新入职同事的项目交接文档”只不过读者是 AI。它放在项目根目录Claude Code 每次启动会自动读取。很多人忽略这个文件结果就是每次都要重复解释项目结构智能体还老是改错地方。一个最小可用的 CLAUDE.md 应该包含这几块项目一句话简介、技术栈、目录结构说明、常用命令、编码规范、禁止事项。我拿一个真实的 Node 后端项目举例# 项目说明 这是一个基于 Express 的订单服务使用 TypeScript 编写。 ## 技术栈 - Node 20 TypeScript 5 - Express 4 Prisma ORM - PostgreSQL 15 - Jest 做单元测试 ## 目录结构 - src/routes 路由层只做参数校验和转发 - src/services 业务逻辑层所有数据库操作在这里 - src/utils 工具函数纯函数不依赖外部状态 ## 常用命令 - npm run dev 启动开发服务 - npm test 跑测试 - npm run lint 代码检查 ## 编码规范 - 所有函数必须有返回类型标注 - 禁止在 routes 层直接调用 Prisma - 错误统一用 AppError 类抛出 ## 禁止事项 - 不要修改 prisma/schema.prisma 除非明确要求 - 不要动 migrations 目录这份文件不长但信息密度高。我实测下来有了它之后智能体改错文件、用错 ORM 方法的概率下降了一大半。3.2 分层写法全局记忆与项目记忆的配合CLAUDE.md 支持分层。除了项目根目录的你还可以在用户主目录放一个全局的~/.claude/CLAUDE.md写一些跨项目通用的偏好比如“回答用中文”“提交信息用约定式提交格式”“优先用函数式写法”。项目级的文件则写项目特有的约定。加载顺序是全局先、项目后项目级会覆盖全局的同名配置。这个分层机制很实用。我全局文件里写了通用的代码风格偏好项目文件里写业务约束两边不打架。有个细节要注意项目级 CLAUDE.md 不要写得太长超过一定长度会挤占上下文窗口反而影响智能体对代码本身的理解。我的经验是控制在 500 行以内重点写“不写会出错”的内容而不是把整个 wiki 搬进来。3.3 让 CLAUDE.md 真正生效的三个技巧第一个技巧是用命令验证。写完 CLAUDE.md 后启动 Claude Code直接问它“这个项目的路由层能不能直接调数据库”看它回答是否符合你的约定。如果答错说明文件没被正确读取或者表述有歧义。第二个技巧是把高频错误写进去。比如你的项目里有个坑某个工具函数必须传时区参数否则会出错。这种“血泪教训”写进 CLAUDE.md智能体就不会再犯。我管这叫“负向记忆”比正向规范更有效。第三个技巧是定期更新。项目架构变了、依赖升级了CLAUDE.md 要同步改。我见过有人 CLAUDE.md 里还写着用 Webpack实际项目早换成 Vite 了结果智能体生成的配置全是错的。建议把更新 CLAUDE.md 纳入代码审查清单改架构的 PR 必须同步更新它。4. Sub-agent 子代理编排把大任务拆成专职小队4.1 为什么需要 Sub-agent上下文隔离的核心价值Sub-agent 是这套“焚诀”里最值钱的部分。传统用法是让一个主代理干所有事问题是上下文会越来越长跑到后面它开始忘前面的事或者被无关信息干扰。Sub-agent 的思路是主代理负责统筹具体任务派给专职子代理每个子代理有独立的上下文窗口干完活只把结论汇报回来。打个比方主代理是项目经理Sub-agent 是各个专项工程师。项目经理不需要知道工程师查了多少文档、试了多少种写法只要拿到最终结果。这样主代理的上下文始终保持干净决策质量就稳。我实测过一个场景给一个 3000 行的模块加单元测试。单代理模式下跑到第 15 个测试用例时它开始重复之前写过的代码明显是上下文被污染了。换成 Sub-agent 模式每个子代理负责 5 个用例主代理只汇总全程没有重复覆盖率还更高。4.2 Sub-agent 的配置方式与角色划分Sub-agent 通过配置文件定义一般放在.claude/agents/目录下每个子代理一个 Markdown 文件。文件里写清楚这个子代理的职责、可用工具、输出格式。举个代码审查子代理的例子--- name: code-reviewer description: 审查代码变更检查规范符合度和潜在 bug tools: Read, Grep, Glob --- 你是一个严格的代码审查员。审查时重点检查 1. 是否符合 CLAUDE.md 里的编码规范 2. 是否有未处理的错误分支 3. 是否有硬编码的敏感信息 4. 数据库操作是否都在 service 层 输出格式按严重程度分级列出问题每条给出文件行号和修改建议。注意tools字段这是子代理能用的工具白名单。审查类子代理只需要读文件不需要写权限这样即使它判断失误也不会改坏代码。这个最小权限原则很重要我后面会专门讲。常见的子代理角色有这么几类探索型查代码库、找相关文件、执行型写代码、改文件、验证型跑测试、做审查、文档型查外部资料、整理说明。一个任务通常派 2 到 4 个子代理就够了派太多反而协调成本高。4.3 编排实战一个完整任务的子代理协作流程我拿“给订单服务加一个退款接口”这个任务走一遍。主代理接到任务后先派探索型子代理去代码库找现有的订单相关代码和类似接口的实现模式拿到文件清单和代码风格参考。然后派执行型子代理按找到的模式写接口代码和对应的 service 层逻辑。写完派验证型子代理跑测试并做代码审查。最后主代理汇总把验证发现的问题反馈给执行型子代理修复。这个流程里主代理的上下文只包含任务描述、各子代理的结论摘要不包含具体的代码细节。所以哪怕任务很大主代理也不会“脑子不够用”。我实测下来这种编排方式处理中等复杂度任务的成功率比单代理高不少返工率明显下降。有个经验要分享子代理之间的依赖要显式声明。比如执行型子代理必须在探索型之后跑因为要用到探索结果。如果并行跑执行型可能拿不到正确的文件清单。我在配置里用depends_on字段标注依赖关系主代理会按顺序调度。5. effort 推理强度控制质量与成本的平衡术5.1 effort 档位的含义与适用场景effort 控制模型在回答前“思考”的深度。低档位响应快、token 省适合简单任务高档位思考充分、质量高但慢且贵。很多人要么一直用低档位图快要么一直用高档位图稳其实都不对。正确的做法是按任务类型动态切换。我的经验分档是这样的改错别字、调整格式、简单重命名用最低档写常规业务代码、改 bug用中档设计架构、排查复杂问题、做代码审查用高档。这个划分不是拍脑袋而是根据任务对“推理链长度”的需求来的。简单任务不需要长推理高档位纯属浪费复杂任务低档位会漏掉边界情况。5.2 动态切换 effort 的实操方法在 Claude Code 里effort 可以在启动时指定也可以在会话中调整。启动时claude --effort high会话中调整的话直接跟它说“接下来这个任务用高 effort 处理”也行但更可靠的方式是在 CLAUDE.md 里写清楚默认档位和切换规则。我一般这么写## effort 使用约定 - 默认使用 medium - 涉及架构设计、复杂 bug 排查时主动提升到 high - 纯格式调整、文案修改使用 low - 每次切换档位前说明理由这样智能体会根据任务自动判断不用我每次手动指定。实测下来这个约定能省不少 token质量也没打折。5.3 成本与质量的量化权衡我做过一个粗略的对比测试同一个“给模块加测试”的任务low 档位跑了 40 秒生成的测试覆盖了主流程但漏了两个边界情况high 档位跑了 3 分钟覆盖了所有分支还额外发现了原代码里的一个潜在空指针问题。token 消耗大概是 1 比 4 的关系。所以我的结论是边界清晰、逻辑简单的任务用低档边界模糊、需要判断的任务用高档。判断标准就是问自己一句这个任务如果交给一个新人他需不需要想很久需要的话就用高档。这个类比很好用我团队里的人都按这个标准来。6. 常见问题与排查技巧实录6.1 安装与升级类问题速查问题现象可能原因解决办法auto-update failed: no write permission to npm prefixnpm 全局目录无写权限改 prefix 到用户目录或管理员权限重装命令找不到 claude全局 bin 目录不在 PATH把 npm 全局 bin 加入 PATH登录卡住不跳转网络或系统时间问题检查网络设置校准系统时间WSL 下安装失败Node 版本过低升级到 Node 20 LTS升级后配置失效新版解析规则变化回滚版本看 release notes 后重配这张表是我和团队踩坑攒出来的基本覆盖了新手会遇到的大部分问题。特别提醒 Windows 用户如果不想折腾权限直接上 WSL省心程度不是一个量级。6.2 Sub-agent 编排失效的排查思路Sub-agent 不按预期工作时按这个顺序排查先确认配置文件路径对不对.claude/agents/目录名和文件名都不能错再看 frontmatter 格式---包裹的元数据必须规范缩进错了会解析失败然后检查tools字段如果子代理需要写文件但白名单里没有 Write它就会静默失败最后看依赖声明顺序错了会导致子代理拿到空结果。我遇到过一次诡异的情况子代理配置全对但就是不执行。排查半天发现是 CLAUDE.md 里有一行格式错误的 Markdown 表格导致整个文件解析中断连带影响了 agents 目录的加载。所以CLAUDE.md 的格式一定要干净写完用 Markdown 预览工具看一眼。6.3 上下文爆炸的预防与处理即使有 Sub-agent主代理的上下文还是可能膨胀。预防手段有三个一是 CLAUDE.md 精简别塞无关内容二是子代理汇报只给结论不给过程三是长会话定期用/clear清空重来把关键结论写进 CLAUDE.md 或单独的笔记文件。如果已经爆炸了表现是智能体开始重复、答非所问、忘记之前的约定。这时候别硬撑清空上下文把当前进度和关键决策写成一个简短的交接文档重新开始。我一般会在任务进行到一半时主动做一次“存档”把已完成部分和待办事项写下来这样即使上下文出问题也能快速恢复。7. 我个人的实操体会与几个压箱底技巧用了这套组合拳大概两个月最大的感受是工具的上限取决于你怎么组织它而不是它本身多强。同样的模型有人用出来是高级补全有人用出来是一个能独立干活的工程小队差别就在 CLAUDE.md 写得够不够准、Sub-agent 分得够不够清、effort 切得够不够对。分享几个我压箱底的技巧。第一个是给子代理写“反面案例”。比如代码审查子代理除了告诉它查什么我还写了一段“以下这些是历史上出现过的真实问题”把踩过的坑列进去。这样它的审查针对性明显更强。第二个是用 effort 做“预检”。大任务开始前先用 low 档位让智能体快速过一遍看它理解的任务范围对不对。如果理解偏了及时纠正再切 high 档正式干。这样避免高档位跑了一半发现方向错了浪费大量 token。第三个是CLAUDE.md 里留一个“变更日志”区块。每次调整项目约定就在里面记一笔写清楚改了什么、为什么改。这样智能体能看到约定的演进历史遇到新旧写法冲突时能判断哪个是最新的。这个技巧比较冷门但实测对减少“用旧写法”的问题很有效。最后说一个心态上的建议别指望一次配置就完美。这套东西是需要养的项目在变你的约定也要跟着变。我现在的习惯是每周花十分钟回顾一下这周智能体犯的错把共性问题补进 CLAUDE.md 或子代理配置里。养上一个月你会发现它越来越顺手那种“它真的懂我项目”的感觉是单纯换个更强模型给不了的。
