1. 这次“焚诀”到底更新了什么Claude Opus 5.5 这个版本号一出来我第一反应是去翻更新日志里跟日常写代码最相关的几个点。说实话模型跑分涨了多少、榜单排第几对天天用 Claude Code 干活的人来说意义不大真正影响手感的是三件事Sub-agent 的调度逻辑、CLAUDE.md 的加载优先级、以及 effort 参数对响应深度和耗时的调节。这三个东西凑在一起才配得上“焚诀”这个说法——它不是单点升级而是把一整套协作方式重新洗了一遍。先把这个标题拆开看。“Claude Opus 5.5”是模型本体“焚诀”是圈子里对那种“一旦用顺了就回不去”的工作流的戏称。而热搜词里高频出现的 Claude Code、Sub-agent、CLAUDE.md、effort恰好就是这套工作流的四个支柱。Claude Code 是载体Sub-agent 是分工方式CLAUDE.md 是长期记忆和规则约束effort 是资源投入的旋钮。你把这四个东西理解透了Opus 5.5 带来的变化才能落到自己的项目里而不是停留在“听说很强”的层面。这篇文章适合谁看如果你已经在用 Claude Code 写代码、做重构、跑测试但总觉得它“有时候聪明有时候犯傻”那这篇就是给你写的。如果你还没上手只是想搞清楚这套东西到底怎么落地我也会把安装、配置、避坑的完整链路讲清楚。我不打算复述官方文档而是按一个真实项目从零到跑通的顺序把每个环节的取舍和踩过的坑摊开讲。需要先说明一点下面涉及的具体参数、目录结构、配置写法一部分来自官方更新说明一部分是我和身边几个重度用户在实际项目里反复试出来的经验值。模型能力在变工具链也在变但底层的协作思路是相对稳定的这才是值得花时间吃透的部分。2. 核心思路拆解为什么是 Sub-agent 加 CLAUDE.md 这套组合2.1 单 Agent 的天花板在哪里早几年用 AI 辅助写代码基本是“一问一答”模式你贴一段代码它给你改一段。这种模式在单文件、小函数级别够用但一旦项目上规模问题立刻暴露。最典型的是上下文污染——你让模型同时记住项目规范、当前任务、历史对话、依赖关系它的注意力会被稀释越到后面越容易跑偏。我试过让一个 Agent 从头到尾负责一个中型重构结果它在第 40 轮对话之后开始忘记前面定好的命名规范把已经改好的模块又改回去。Sub-agent 的思路就是把这个“一个人扛所有事”的模式拆掉。主 Agent 负责理解需求、拆解任务、分派工作子 Agent 各自负责一块具体的事比如一个专门读代码库结构一个专门写测试一个专门做代码审查。每个子 Agent 的上下文是独立的、聚焦的不会被无关信息干扰。这就像现实里的开发团队你不会让一个人同时做架构设计、写业务代码、跑测试、做 Code Review而是分工协作。2.2 CLAUDE.md 扮演的是什么角色如果说 Sub-agent 解决的是“怎么分工”那 CLAUDE.md 解决的就是“按什么规矩干活”。这个文件放在项目根目录Claude Code 启动时会自动读取相当于给整个 Agent 团队发了一本员工手册。里面通常写这几类内容项目的技术栈和版本约束、代码风格和命名规范、目录结构说明、常用命令、以及一些“绝对不要做”的红线。我见过很多人把 CLAUDE.md 写成一份冗长的 README这是典型的误区。CLAUDE.md 的核心价值在于约束不是介绍。README 是给人看的讲这个项目是什么CLAUDE.md 是给 Agent 看的讲在这个项目里应该怎么做事。所以它应该短、准、可执行。比如“所有 API 请求必须走 src/utils/request.ts 封装”这种比“本项目使用 axios 做网络请求”有用得多因为前者是规则后者只是背景。2.3 effort 参数为什么值得单独拎出来说effort 这个词在热搜里出现说明大家已经意识到它不是个可有可无的开关。简单说effort 控制的是模型在回答前“愿意花多少力气思考”。低 effort 响应快、省资源适合改个变量名、补个注释这种小事高 effort 会做更充分的推理和自检适合架构设计、复杂 bug 排查这种硬骨头。关键在于不是所有任务都值得开高 effort。我早期犯过一个错所有请求都拉满 effort结果一个简单的格式化任务等了快一分钟才出结果纯属浪费。后来我养成的习惯是把 effort 当成一个需要主动管理的资源按任务复杂度动态调整。这个思路和 Sub-agent 的分工逻辑是一脉相承的——把合适的资源投到合适的地方。2.4 四者如何咬合成一个整体把这四个东西串起来看Claude Code 是运行环境CLAUDE.md 定义规则Sub-agent 负责分工effort 调节每个子任务的投入。一个典型的协作流程是这样的——主 Agent 读取 CLAUDE.md 了解项目约束把“给用户模块加一个导出功能”拆成几个子任务分派给不同的 Sub-agent每个子 Agent 根据自己的任务复杂度选择合适的 effort完成后把结果汇总回主 Agent 做整合和校验。这套组合的威力在于它把“一个大模型硬扛”变成了“一支有纪律的小队协作”。Opus 5.5 在这个基础上的提升主要体现在子 Agent 之间的信息传递更准确、CLAUDE.md 的规则遵循度更高、effort 的调节更细腻。理解了这套骨架后面的实操才有落脚点。3. 从零跑通 Claude Code 的完整链路3.1 安装前的环境确认在动手之前先把环境确认清楚能省掉后面一大半的报错。Claude Code 本质是个命令行工具对运行环境有基本要求。如果你在 Windows 上官方推荐走 WSL因为原生 Windows 环境下路径处理和权限模型容易出问题。我实测下来WSL2 加 Ubuntu 的组合最稳Windows 原生环境虽然也能跑但遇到权限相关的报错概率明显更高。Node.js 版本建议 18 以上npm 用自带的就行。装之前先跑一遍node -v和npm -v确认版本如果 Node 太老后面安装依赖时会报一堆莫名其妙的错。另外确认一下 npm 的全局安装目录有没有写权限这个后面会专门讲因为它是最高频的报错来源之一。3.2 安装步骤与验证安装本身不复杂一条命令的事npm install -g anthropic-ai/claude-code装完之后用claude --version验证一下。如果提示命令找不到八成是 npm 全局 bin 目录没加到 PATH 里。这时候跑npm config get prefix看看全局目录在哪然后把这个目录下的 bin 加进环境变量。提示如果你用的是 nvm 管理 Node 版本全局包是跟着 Node 版本走的。切换 Node 版本后可能需要重新安装这点容易忽略。安装完成后第一次启动会引导你做登录和初始化配置。这个过程按提示走就行不需要额外折腾。初始化完成后Claude Code 会在你的项目目录下生成配置相关的文件这时候就可以开始配置 CLAUDE.md 了。3.3 CLAUDE.md 的写法与分层CLAUDE.md 支持分层这是很多人不知道的细节。你可以在项目根目录放一个也可以在子目录放一个Claude Code 会按层级加载。根目录的写全局规则子目录的写该模块特有的约定。比如根目录写“所有代码用 TypeScript 严格模式”src/api/目录下再写“所有接口返回统一用 ApiResponse 类型包装”。一个实用的 CLAUDE.md 模板大概长这样# 项目约定 ## 技术栈 - 框架Next.js 14 App Router - 语言TypeScript 5.xstrict 模式 - 样式Tailwind CSS ## 代码规范 - 组件文件用 PascalCase工具函数用 camelCase - 所有异步操作必须处理错误不允许裸 await - 禁止使用 any必要时用 unknown 加类型守卫 ## 常用命令 - 开发npm run dev - 测试npm run test - 类型检查npm run typecheck ## 红线 - 不要修改 src/config/ 下的任何文件 - 不要引入新的第三方依赖除非明确要求这个文件的关键是可执行。每一条都应该是 Agent 能直接判断“做没做到”的规则而不是模糊的描述。写完可以自己读一遍问自己如果我是 Agent看到这条知道具体该怎么做吗如果答案是模糊的就改到具体为止。3.4 Sub-agent 的配置与分工Sub-agent 的配置通常写在 CLAUDE.md 里或者单独的配置文件里定义每个子 Agent 的职责范围、可用的工具、以及和其他 Agent 的协作方式。一个常见的分工方案是子 Agent职责适用场景explorer读代码库、定位相关文件任务开始前的调研coder写业务代码具体功能实现tester写和跑测试功能完成后验证reviewer代码审查提交前的质量把关配置的时候要注意子 Agent 的职责边界要清晰重叠越少越好。我见过有人配了两个都负责“写代码”的子 Agent结果它们互相覆盖对方的改动反而更乱。每个子 Agent 应该只做一件事做深做透。3.5 effort 的动态调节策略effort 的调节没有绝对标准但有个经验法则任务的不确定性越高effort 越高。改个拼写错误低 effort 足够排查一个偶发的并发 bug高 effort 才可能找到根因。我一般分三档来用低档格式化、重命名、补注释、简单查询中档常规功能开发、单元测试编写、代码重构高档架构设计、复杂 bug 排查、性能优化方案实际操作中我会在任务描述里明确告诉 Agent 这个任务大概需要什么档位让它自己判断。Opus 5.5 在这块的判断比之前准了不少但关键任务我还是会手动指定避免它“偷懒”。4. 实操过程中的关键环节与参数取舍4.1 一个真实重构任务的完整流程拿我最近做的一个任务举例把一个老项目的状态管理从 Redux 迁移到 Zustand。这个任务涉及几十个文件手动改至少要两天。我的做法是先用 explorer 子 Agent 扫一遍代码库列出所有用到 Redux 的文件和具体用法生成一份清单。这一步用中档 effort大概几分钟出结果。拿到清单后主 Agent 按模块拆成若干子任务每个子任务分给一个 coder 子 Agent。这里有个细节不要让所有 coder 同时开工因为状态管理迁移涉及共享的 store 定义并行改容易冲突。我的做法是先让一个 coder 把 store 的骨架搭好确认无误后再并行处理各个业务模块。每个模块改完后tester 子 Agent 跑对应的测试reviewer 子 Agent 检查有没有遗漏的 Redux 引用。整个流程跑下来实际耗时不到半天而且改动的一致性比手动改好很多。这个案例里Sub-agent 的分工和 effort 的分档是效率的关键CLAUDE.md 里写死的“状态管理统一用 Zustand”这条规则则保证了方向不跑偏。4.2 参数选择背后的计算逻辑effort 的选择其实可以量化。我自己的经验公式是effort 档位 ≈ 任务涉及的文件数 × 逻辑分支复杂度。文件数好理解逻辑分支复杂度指的是这个任务里有多少条件判断、边界情况、异常处理。一个涉及 3 个文件、逻辑简单的任务低到中档就够一个涉及 10 个以上文件、有大量边界情况的任务直接上高档。这个公式不是精确科学但它能帮你建立一个直觉任务越“重”投入越多。避免两个极端——要么所有任务都低 effort 导致质量差要么所有任务都高 effort 导致效率低。4.3 上下文管理的关键技巧Sub-agent 虽然隔离了上下文但主 Agent 的上下文还是有限的。一个常见的坑是任务做到一半主 Agent 的上下文被历史信息塞满开始“失忆”。我的应对办法是定期让主 Agent 输出一份进度摘要把已完成的部分、待办的部分、关键决策记下来然后开一个新的会话继续。这份摘要可以存成文件下次启动时让 Agent 先读它。另一个技巧是把大任务拆成多个独立的会话每个会话专注一个模块。这样每个会话的上下文都是干净的不会互相干扰。代价是需要手动管理会话之间的衔接但换来的是每个环节的质量稳定。4.4 与现有工具链的集成Claude Code 不是孤立的它要和你现有的工具链配合。最常见的集成点是 Git、测试框架、Lint 工具。我的做法是在 CLAUDE.md 里明确写清楚这些工具的用法比如“提交前必须跑 npm run lint 和 npm run test两者都通过才能提交”。这样 Agent 在完成任务后会自动走这套流程不需要你每次提醒。还有一个细节是 Git 分支策略。我一般让 Agent 在独立分支上工作完成后由我 review 再合并。这样即使 Agent 改错了也不会污染主分支。CLAUDE.md 里可以写明分支命名规范比如feat/开头是功能fix/开头是修复。5. 常见报错与排查技巧实录5.1 安装与权限类问题最高频的报错是auto-update failed: no write permission to npm prefix。这个问题的根源是 npm 全局目录没有写权限Agent 想自动更新但更新不了。解决办法有两个一是用sudo chown -R $(whoami) $(npm config get prefix)把目录所有权改回来二是干脆关掉自动更新手动更新。我倾向后者因为自动更新有时候会在你干活干到一半时打断你。另一个常见问题是找不到start in cowork on 3 p这类提示。这通常是初始化配置没走完或者配置文件损坏。最省事的办法是删掉配置目录重新初始化虽然要重来一遍但比一个个排查快。5.2 模型接入与登录问题关于“能不能不登录用其他模型”这个要看你用的具体版本和配置方式。有些场景下可以配置自定义的模型端点但配置过程比默认登录复杂而且不同版本的配置方式不一样。我的建议是先用默认方式跑通确认整个链路没问题之后再考虑接入其他模型。一上来就折腾自定义配置很容易卡在某个环节出不来。登录相关的问题大部分是网络环境导致的。如果你遇到登录卡住先确认网络能正常访问相关服务再检查有没有代理配置冲突。这块的具体排查步骤因环境而异核心思路是先把网络链路确认清楚再排查应用层配置。5.3 运行时的典型故障报错现象可能原因排查方向Agent 反复改同一个文件CLAUDE.md 规则冲突检查规则是否有矛盾子 Agent 之间改动覆盖职责边界不清重新划分 Sub-agent 职责任务做到一半失忆上下文溢出拆分会话输出进度摘要测试一直失败但代码看着对环境依赖没装检查依赖和版本响应特别慢effort 档位过高按任务复杂度调低这张表是我踩坑踩出来的基本覆盖了日常 80% 的问题。遇到报错先对照这张表能快速定位方向不用从头排查。5.4 独家避坑经验说几个文档里不会写、但实际很要命的点。第一CLAUDE.md 不要写太长。我试过写了一份 500 行的规则文件结果 Agent 反而抓不住重点经常忽略关键规则。后来精简到 50 行以内遵循度明显提升。规则不在多在于每条都清晰可执行。第二Sub-agent 的数量不要贪多。三个到四个是比较舒服的区间再多协调成本就上来了。我见过有人配了七八个子 Agent结果主 Agent 光是在分派任务上就耗掉大量上下文得不偿失。第三关键改动一定要人工 review。Agent 再强也会有盲区尤其是涉及业务逻辑的改动它可能改得“语法正确但语义错误”。我的习惯是每个模块改完后自己扫一遍 diff重点看逻辑分支和边界处理这个习惯帮我拦下过好几次隐蔽的 bug。第四定期更新 CLAUDE.md。项目在演进规则也要跟着变。我一般每个迭代周期结束会花十分钟过一遍 CLAUDE.md把过时的规则删掉把新踩的坑补进去。这个习惯让规则文件始终保持“活着”的状态而不是变成一份没人维护的僵尸文档。6. 把这套工作流用顺的几个心得用到现在我最大的体会是这套工具的价值不在于模型多聪明而在于你有没有把规则和分工设计好。同样的 Opus 5.5有人用起来效率翻倍有人用起来还不如手动写差别就在 CLAUDE.md 的质量和 Sub-agent 的划分上。模型是引擎但方向盘和路线图是你给的。另一个心得是别追求一步到位。我刚开始用的时候总想一次性把所有配置都调完美结果卡在配置上耗了好几天代码一行没写。后来想通了先用最简配置跑起来遇到问题再针对性调整反而上手更快。工具是拿来用的不是拿来供着的。最后分享一个我最近在用的技巧把每次踩的坑和对应的解决办法记在一个单独的LESSONS.md里和 CLAUDE.md 放在一起。下次遇到类似问题直接让 Agent 读这个文件它就能避开之前踩过的坑。这个文件越攒越厚Agent 的“经验”也就越来越足某种程度上相当于给它做了一套持续积累的错题本。
1. 这次“焚诀”到底更新了什么Claude Opus 5.5 这个版本号一出来我第一反应是去翻更新日志里跟日常写代码最相关的几个点。说实话模型跑分涨了多少、榜单排第几对天天用 Claude Code 干活的人来说意义不大真正影响手感的是三件事Sub-agent 的调度逻辑、CLAUDE.md 的加载优先级、以及 effort 参数对响应深度和耗时的调节。这三个东西凑在一起才配得上“焚诀”这个说法——它不是单点升级而是把一整套协作方式重新洗了一遍。先把这个标题拆开看。“Claude Opus 5.5”是模型本体“焚诀”是圈子里对那种“一旦用顺了就回不去”的工作流的戏称。而热搜词里高频出现的 Claude Code、Sub-agent、CLAUDE.md、effort恰好就是这套工作流的四个支柱。Claude Code 是载体Sub-agent 是分工方式CLAUDE.md 是长期记忆和规则约束effort 是资源投入的旋钮。你把这四个东西理解透了Opus 5.5 带来的变化才能落到自己的项目里而不是停留在“听说很强”的层面。这篇文章适合谁看如果你已经在用 Claude Code 写代码、做重构、跑测试但总觉得它“有时候聪明有时候犯傻”那这篇就是给你写的。如果你还没上手只是想搞清楚这套东西到底怎么落地我也会把安装、配置、避坑的完整链路讲清楚。我不打算复述官方文档而是按一个真实项目从零到跑通的顺序把每个环节的取舍和踩过的坑摊开讲。需要先说明一点下面涉及的具体参数、目录结构、配置写法一部分来自官方更新说明一部分是我和身边几个重度用户在实际项目里反复试出来的经验值。模型能力在变工具链也在变但底层的协作思路是相对稳定的这才是值得花时间吃透的部分。2. 核心思路拆解为什么是 Sub-agent 加 CLAUDE.md 这套组合2.1 单 Agent 的天花板在哪里早几年用 AI 辅助写代码基本是“一问一答”模式你贴一段代码它给你改一段。这种模式在单文件、小函数级别够用但一旦项目上规模问题立刻暴露。最典型的是上下文污染——你让模型同时记住项目规范、当前任务、历史对话、依赖关系它的注意力会被稀释越到后面越容易跑偏。我试过让一个 Agent 从头到尾负责一个中型重构结果它在第 40 轮对话之后开始忘记前面定好的命名规范把已经改好的模块又改回去。Sub-agent 的思路就是把这个“一个人扛所有事”的模式拆掉。主 Agent 负责理解需求、拆解任务、分派工作子 Agent 各自负责一块具体的事比如一个专门读代码库结构一个专门写测试一个专门做代码审查。每个子 Agent 的上下文是独立的、聚焦的不会被无关信息干扰。这就像现实里的开发团队你不会让一个人同时做架构设计、写业务代码、跑测试、做 Code Review而是分工协作。2.2 CLAUDE.md 扮演的是什么角色如果说 Sub-agent 解决的是“怎么分工”那 CLAUDE.md 解决的就是“按什么规矩干活”。这个文件放在项目根目录Claude Code 启动时会自动读取相当于给整个 Agent 团队发了一本员工手册。里面通常写这几类内容项目的技术栈和版本约束、代码风格和命名规范、目录结构说明、常用命令、以及一些“绝对不要做”的红线。我见过很多人把 CLAUDE.md 写成一份冗长的 README这是典型的误区。CLAUDE.md 的核心价值在于约束不是介绍。README 是给人看的讲这个项目是什么CLAUDE.md 是给 Agent 看的讲在这个项目里应该怎么做事。所以它应该短、准、可执行。比如“所有 API 请求必须走 src/utils/request.ts 封装”这种比“本项目使用 axios 做网络请求”有用得多因为前者是规则后者只是背景。2.3 effort 参数为什么值得单独拎出来说effort 这个词在热搜里出现说明大家已经意识到它不是个可有可无的开关。简单说effort 控制的是模型在回答前“愿意花多少力气思考”。低 effort 响应快、省资源适合改个变量名、补个注释这种小事高 effort 会做更充分的推理和自检适合架构设计、复杂 bug 排查这种硬骨头。关键在于不是所有任务都值得开高 effort。我早期犯过一个错所有请求都拉满 effort结果一个简单的格式化任务等了快一分钟才出结果纯属浪费。后来我养成的习惯是把 effort 当成一个需要主动管理的资源按任务复杂度动态调整。这个思路和 Sub-agent 的分工逻辑是一脉相承的——把合适的资源投到合适的地方。2.4 四者如何咬合成一个整体把这四个东西串起来看Claude Code 是运行环境CLAUDE.md 定义规则Sub-agent 负责分工effort 调节每个子任务的投入。一个典型的协作流程是这样的——主 Agent 读取 CLAUDE.md 了解项目约束把“给用户模块加一个导出功能”拆成几个子任务分派给不同的 Sub-agent每个子 Agent 根据自己的任务复杂度选择合适的 effort完成后把结果汇总回主 Agent 做整合和校验。这套组合的威力在于它把“一个大模型硬扛”变成了“一支有纪律的小队协作”。Opus 5.5 在这个基础上的提升主要体现在子 Agent 之间的信息传递更准确、CLAUDE.md 的规则遵循度更高、effort 的调节更细腻。理解了这套骨架后面的实操才有落脚点。3. 从零跑通 Claude Code 的完整链路3.1 安装前的环境确认在动手之前先把环境确认清楚能省掉后面一大半的报错。Claude Code 本质是个命令行工具对运行环境有基本要求。如果你在 Windows 上官方推荐走 WSL因为原生 Windows 环境下路径处理和权限模型容易出问题。我实测下来WSL2 加 Ubuntu 的组合最稳Windows 原生环境虽然也能跑但遇到权限相关的报错概率明显更高。Node.js 版本建议 18 以上npm 用自带的就行。装之前先跑一遍node -v和npm -v确认版本如果 Node 太老后面安装依赖时会报一堆莫名其妙的错。另外确认一下 npm 的全局安装目录有没有写权限这个后面会专门讲因为它是最高频的报错来源之一。3.2 安装步骤与验证安装本身不复杂一条命令的事npm install -g anthropic-ai/claude-code装完之后用claude --version验证一下。如果提示命令找不到八成是 npm 全局 bin 目录没加到 PATH 里。这时候跑npm config get prefix看看全局目录在哪然后把这个目录下的 bin 加进环境变量。提示如果你用的是 nvm 管理 Node 版本全局包是跟着 Node 版本走的。切换 Node 版本后可能需要重新安装这点容易忽略。安装完成后第一次启动会引导你做登录和初始化配置。这个过程按提示走就行不需要额外折腾。初始化完成后Claude Code 会在你的项目目录下生成配置相关的文件这时候就可以开始配置 CLAUDE.md 了。3.3 CLAUDE.md 的写法与分层CLAUDE.md 支持分层这是很多人不知道的细节。你可以在项目根目录放一个也可以在子目录放一个Claude Code 会按层级加载。根目录的写全局规则子目录的写该模块特有的约定。比如根目录写“所有代码用 TypeScript 严格模式”src/api/目录下再写“所有接口返回统一用 ApiResponse 类型包装”。一个实用的 CLAUDE.md 模板大概长这样# 项目约定 ## 技术栈 - 框架Next.js 14 App Router - 语言TypeScript 5.xstrict 模式 - 样式Tailwind CSS ## 代码规范 - 组件文件用 PascalCase工具函数用 camelCase - 所有异步操作必须处理错误不允许裸 await - 禁止使用 any必要时用 unknown 加类型守卫 ## 常用命令 - 开发npm run dev - 测试npm run test - 类型检查npm run typecheck ## 红线 - 不要修改 src/config/ 下的任何文件 - 不要引入新的第三方依赖除非明确要求这个文件的关键是可执行。每一条都应该是 Agent 能直接判断“做没做到”的规则而不是模糊的描述。写完可以自己读一遍问自己如果我是 Agent看到这条知道具体该怎么做吗如果答案是模糊的就改到具体为止。3.4 Sub-agent 的配置与分工Sub-agent 的配置通常写在 CLAUDE.md 里或者单独的配置文件里定义每个子 Agent 的职责范围、可用的工具、以及和其他 Agent 的协作方式。一个常见的分工方案是子 Agent职责适用场景explorer读代码库、定位相关文件任务开始前的调研coder写业务代码具体功能实现tester写和跑测试功能完成后验证reviewer代码审查提交前的质量把关配置的时候要注意子 Agent 的职责边界要清晰重叠越少越好。我见过有人配了两个都负责“写代码”的子 Agent结果它们互相覆盖对方的改动反而更乱。每个子 Agent 应该只做一件事做深做透。3.5 effort 的动态调节策略effort 的调节没有绝对标准但有个经验法则任务的不确定性越高effort 越高。改个拼写错误低 effort 足够排查一个偶发的并发 bug高 effort 才可能找到根因。我一般分三档来用低档格式化、重命名、补注释、简单查询中档常规功能开发、单元测试编写、代码重构高档架构设计、复杂 bug 排查、性能优化方案实际操作中我会在任务描述里明确告诉 Agent 这个任务大概需要什么档位让它自己判断。Opus 5.5 在这块的判断比之前准了不少但关键任务我还是会手动指定避免它“偷懒”。4. 实操过程中的关键环节与参数取舍4.1 一个真实重构任务的完整流程拿我最近做的一个任务举例把一个老项目的状态管理从 Redux 迁移到 Zustand。这个任务涉及几十个文件手动改至少要两天。我的做法是先用 explorer 子 Agent 扫一遍代码库列出所有用到 Redux 的文件和具体用法生成一份清单。这一步用中档 effort大概几分钟出结果。拿到清单后主 Agent 按模块拆成若干子任务每个子任务分给一个 coder 子 Agent。这里有个细节不要让所有 coder 同时开工因为状态管理迁移涉及共享的 store 定义并行改容易冲突。我的做法是先让一个 coder 把 store 的骨架搭好确认无误后再并行处理各个业务模块。每个模块改完后tester 子 Agent 跑对应的测试reviewer 子 Agent 检查有没有遗漏的 Redux 引用。整个流程跑下来实际耗时不到半天而且改动的一致性比手动改好很多。这个案例里Sub-agent 的分工和 effort 的分档是效率的关键CLAUDE.md 里写死的“状态管理统一用 Zustand”这条规则则保证了方向不跑偏。4.2 参数选择背后的计算逻辑effort 的选择其实可以量化。我自己的经验公式是effort 档位 ≈ 任务涉及的文件数 × 逻辑分支复杂度。文件数好理解逻辑分支复杂度指的是这个任务里有多少条件判断、边界情况、异常处理。一个涉及 3 个文件、逻辑简单的任务低到中档就够一个涉及 10 个以上文件、有大量边界情况的任务直接上高档。这个公式不是精确科学但它能帮你建立一个直觉任务越“重”投入越多。避免两个极端——要么所有任务都低 effort 导致质量差要么所有任务都高 effort 导致效率低。4.3 上下文管理的关键技巧Sub-agent 虽然隔离了上下文但主 Agent 的上下文还是有限的。一个常见的坑是任务做到一半主 Agent 的上下文被历史信息塞满开始“失忆”。我的应对办法是定期让主 Agent 输出一份进度摘要把已完成的部分、待办的部分、关键决策记下来然后开一个新的会话继续。这份摘要可以存成文件下次启动时让 Agent 先读它。另一个技巧是把大任务拆成多个独立的会话每个会话专注一个模块。这样每个会话的上下文都是干净的不会互相干扰。代价是需要手动管理会话之间的衔接但换来的是每个环节的质量稳定。4.4 与现有工具链的集成Claude Code 不是孤立的它要和你现有的工具链配合。最常见的集成点是 Git、测试框架、Lint 工具。我的做法是在 CLAUDE.md 里明确写清楚这些工具的用法比如“提交前必须跑 npm run lint 和 npm run test两者都通过才能提交”。这样 Agent 在完成任务后会自动走这套流程不需要你每次提醒。还有一个细节是 Git 分支策略。我一般让 Agent 在独立分支上工作完成后由我 review 再合并。这样即使 Agent 改错了也不会污染主分支。CLAUDE.md 里可以写明分支命名规范比如feat/开头是功能fix/开头是修复。5. 常见报错与排查技巧实录5.1 安装与权限类问题最高频的报错是auto-update failed: no write permission to npm prefix。这个问题的根源是 npm 全局目录没有写权限Agent 想自动更新但更新不了。解决办法有两个一是用sudo chown -R $(whoami) $(npm config get prefix)把目录所有权改回来二是干脆关掉自动更新手动更新。我倾向后者因为自动更新有时候会在你干活干到一半时打断你。另一个常见问题是找不到start in cowork on 3 p这类提示。这通常是初始化配置没走完或者配置文件损坏。最省事的办法是删掉配置目录重新初始化虽然要重来一遍但比一个个排查快。5.2 模型接入与登录问题关于“能不能不登录用其他模型”这个要看你用的具体版本和配置方式。有些场景下可以配置自定义的模型端点但配置过程比默认登录复杂而且不同版本的配置方式不一样。我的建议是先用默认方式跑通确认整个链路没问题之后再考虑接入其他模型。一上来就折腾自定义配置很容易卡在某个环节出不来。登录相关的问题大部分是网络环境导致的。如果你遇到登录卡住先确认网络能正常访问相关服务再检查有没有代理配置冲突。这块的具体排查步骤因环境而异核心思路是先把网络链路确认清楚再排查应用层配置。5.3 运行时的典型故障报错现象可能原因排查方向Agent 反复改同一个文件CLAUDE.md 规则冲突检查规则是否有矛盾子 Agent 之间改动覆盖职责边界不清重新划分 Sub-agent 职责任务做到一半失忆上下文溢出拆分会话输出进度摘要测试一直失败但代码看着对环境依赖没装检查依赖和版本响应特别慢effort 档位过高按任务复杂度调低这张表是我踩坑踩出来的基本覆盖了日常 80% 的问题。遇到报错先对照这张表能快速定位方向不用从头排查。5.4 独家避坑经验说几个文档里不会写、但实际很要命的点。第一CLAUDE.md 不要写太长。我试过写了一份 500 行的规则文件结果 Agent 反而抓不住重点经常忽略关键规则。后来精简到 50 行以内遵循度明显提升。规则不在多在于每条都清晰可执行。第二Sub-agent 的数量不要贪多。三个到四个是比较舒服的区间再多协调成本就上来了。我见过有人配了七八个子 Agent结果主 Agent 光是在分派任务上就耗掉大量上下文得不偿失。第三关键改动一定要人工 review。Agent 再强也会有盲区尤其是涉及业务逻辑的改动它可能改得“语法正确但语义错误”。我的习惯是每个模块改完后自己扫一遍 diff重点看逻辑分支和边界处理这个习惯帮我拦下过好几次隐蔽的 bug。第四定期更新 CLAUDE.md。项目在演进规则也要跟着变。我一般每个迭代周期结束会花十分钟过一遍 CLAUDE.md把过时的规则删掉把新踩的坑补进去。这个习惯让规则文件始终保持“活着”的状态而不是变成一份没人维护的僵尸文档。6. 把这套工作流用顺的几个心得用到现在我最大的体会是这套工具的价值不在于模型多聪明而在于你有没有把规则和分工设计好。同样的 Opus 5.5有人用起来效率翻倍有人用起来还不如手动写差别就在 CLAUDE.md 的质量和 Sub-agent 的划分上。模型是引擎但方向盘和路线图是你给的。另一个心得是别追求一步到位。我刚开始用的时候总想一次性把所有配置都调完美结果卡在配置上耗了好几天代码一行没写。后来想通了先用最简配置跑起来遇到问题再针对性调整反而上手更快。工具是拿来用的不是拿来供着的。最后分享一个我最近在用的技巧把每次踩的坑和对应的解决办法记在一个单独的LESSONS.md里和 CLAUDE.md 放在一起。下次遇到类似问题直接让 Agent 读这个文件它就能避开之前踩过的坑。这个文件越攒越厚Agent 的“经验”也就越来越足某种程度上相当于给它做了一套持续积累的错题本。
