Claude Opus 5.5 智能体编程工作流：CLAUDE.md 与 Sub-agent 实战指南

1. 从“焚诀”说起：这个标题到底在讲什么

第一次看到“焚诀”这个词，我愣了两秒。这不是什么玄幻小说里的功法，而是圈内人对 Claude 系列模型一次重大版本更新的戏称——意思是“烧掉旧套路、重写新规则”的那种大版本迭代。标题里挂着“Claude Opus 5.5”，配合热搜词里的 Claude Code、CLAUDE.md、Sub-agent、effort，基本可以判断：这是一次围绕智能体编程工作流的深度升级，而不是单纯的模型跑分提升。

先把话说清楚：这篇内容不是官方发布稿的翻译，也不是参数罗列。我想做的是把这次更新背后真正影响日常开发的那几条线拆开——CLAUDE.md 的工程化用法、Sub-agent 的任务拆分逻辑、effort 参数对成本和质量的调节、以及 Claude Code 在真实项目里的落地姿势。如果你正在用 Claude Code 写代码、做重构、跑自动化任务，或者你只是听说过这个名字但一直没搞明白它和普通对话式 AI 有什么区别，那这篇内容应该能帮你省下不少自己摸索的时间。

我自己的使用场景比较典型：一个中等规模的 TypeScript 全栈项目，前后端加起来大概四万行代码，日常需要做接口联调、写测试、改 bug、偶尔重构。之前用对话式 AI 的体验是——每次都要把上下文重新喂一遍，改到第三个文件的时候它已经忘了第一个文件的结构。Claude Code 这类工具出现的意义，就是把这个“反复喂上下文”的过程变成项目级的持久记忆 + 任务级的自动拆解。而这次 Opus 5.5 带来的变化，恰好集中在这两个点上。

所以下面我会按四个层次来讲：先讲整体设计思路和这次更新的核心取向，再拆 CLAUDE.md 和 Sub-agent 这两个最关键的机制，然后是完整的实操流程和参数调节，最后是我踩过的坑和排查方法。每一部分都会给出可以直接抄的配置和命令，不玩虚的。

2. 整体设计思路：为什么是“项目记忆 + 任务拆分”这条路

2.1 从“对话”到“工程”的范式转移

普通对话式 AI 的工作模式是：你问一句，它答一句，上下文窗口就是它的全部记忆。这个模式在写一个函数、解释一段报错的时候够用，但一旦进入真实项目就立刻暴露问题。真实项目的代码不是孤立的片段，它有一整套隐含约定——目录结构怎么组织、状态管理用哪个库、错误处理统一走哪个中间件、命名规范是 camelCase 还是 snake_case。这些东西你不可能每次对话都重新说一遍。

Claude Code 这类工具的核心设计，就是把这些“隐含约定”显式化、持久化。它通过一个叫CLAUDE.md的文件，把项目级的规则写下来，让模型每次进入这个项目时自动读取。这本质上和新人入职时看的那份《项目开发规范》是同一个东西——只不过读者从人变成了 AI。

这次 Opus 5.5 在这个方向上的推进，我理解主要是两点：一是 CLAUDE.md 的解析和优先级处理更细了，支持分层覆盖；二是 Sub-agent 机制让复杂任务可以被拆成多个独立上下文去执行，避免单个上下文被塞爆。这两点合起来，解决的是“大项目里 AI 记不住、理不清”的老大难问题。

2.2 方案选型背后的取舍：为什么不做“全自动”

市面上有些工具走的是“全自动”路线——你给一个需求，它自己规划、自己写、自己测、自己提交。听起来很爽，但实际用下来问题很多：它可能改了你不想让它改的文件，可能引入你团队不接受的依赖，可能在你没注意的时候删掉一段看似无用实则关键的兼容代码。

Claude Code 的取向明显更保守：它把控制权留在人手里。Sub-agent 拆分任务，但每个子任务的执行边界是你划定的；effort 参数调节投入程度，但要不要继续是你决定的；CLAUDE.md 定义规则，但规则是你写的。这种“人在环中”的设计，短期看不如全自动酷炫，长期看才是能真正进生产环境的方案。

我举个具体例子。之前让 AI 帮我重构一个数据处理的模块，全自动模式下它直接把一个同步函数改成了异步，调用方全崩了。后来用 Claude Code 的 Sub-agent 模式，我先让它只分析依赖关系、输出一份改动清单，我确认之后再让它逐个文件改。多了一步确认，但省下了半天 debug 的时间。这个取舍我认为是值得的。

2.3 这次更新对哪类人影响最大

不是所有人都需要关心这些。如果你只是偶尔用 AI 写个小脚本、查个语法，那这次更新对你感知不强。但如果你符合下面任意一条，那值得花时间研究：

• 维护一个超过一万行的代码库，经常需要跨文件改动
• 团队里有多人协作，需要统一 AI 辅助的规范
• 做重复性的代码任务（写测试、补类型、改 API 调用），希望批量化
• 已经在用 Claude Code，但感觉效果不稳定、时好时坏

最后一类人尤其要注意。很多人用 Claude Code 效果不好，不是模型不行，而是没写 CLAUDE.md，或者写了但写得太笼统。模型每次都在猜你的项目约定，猜对了是运气，猜错了就怪模型。这次更新把 CLAUDE.md 的机制强化了，正好是补课的机会。

3. 核心机制拆解：CLAUDE.md 与 Sub-agent 到底怎么用

3.1 CLAUDE.md 的分层结构与优先级

CLAUDE.md 不是一个单文件，而是一套分层覆盖的规则体系。我实测下来，它至少支持三个层级：

优先级是就近覆盖：目录层 > 项目层 > 全局层。这个设计很合理，因为不同模块的约定本来就可能不一样。比如前端目录要求用函数式组件，后端目录要求用类，这种差异用分层来管理最自然。

我自己的项目层 CLAUDE.md 大概长这样，你可以参考这个结构：

# 项目约定 ## 技术栈 - 语言：TypeScript 5.x，严格模式 - 框架：React 18 + Vite - 状态：Zustand，禁止引入 Redux - 请求：统一走 src/api/client.ts 封装 ## 目录结构 - src/components：纯展示组件，不含业务逻辑 - src/features：按功能模块组织，每个模块自带 hooks 和 api - src/utils：无副作用的纯函数 ## 编码规范 - 组件文件用 PascalCase，工具文件用 camelCase - 禁止使用 any，必要时用 unknown + 类型守卫 - 所有异步函数必须处理错误，不允许裸 await ## 常用命令 - 开发：pnpm dev - 测试：pnpm test --run - 类型检查：pnpm tsc --noEmit

关键心得：CLAUDE.md 要写“约束”，不要写“介绍”。很多人写成像 README 一样，介绍项目是干什么的、有什么功能。模型不需要这些，它需要的是“你不能做什么”和“你必须怎么做”。约束越明确，输出越稳定。

3.2 Sub-agent 的任务拆分逻辑

Sub-agent 是这次更新里我觉得最有价值的部分。它的核心思想是：一个复杂任务不要塞给一个上下文，而是拆成多个子任务，每个子任务有独立的上下文窗口。

为什么这很重要？因为上下文窗口是有限资源。当你让 AI 改一个涉及十个文件的重构时，如果全塞在一个上下文里，读到第七个文件时前面的内容已经开始被挤出去了，它就会“忘记”最初的约束。Sub-agent 把任务拆开，每个子任务只关心自己那部分，上下文压力小，输出质量自然高。

拆分的粒度怎么把握？我的经验是按“可独立验证的单元”来拆。比如一个 API 重构任务，可以拆成：

1. 分析现有 API 的调用点，输出清单
2. 修改 API 定义文件
3. 逐个修改调用点
4. 跑类型检查和测试验证

每个子任务都有明确的输入和输出，可以独立判断对错。如果拆成“改前半部分”和“改后半部分”，就没有独立验证的标准，反而容易出问题。

这里有个实操细节：Sub-agent 之间需要传递信息。比如子任务 1 输出的调用点清单，要传给子任务 3。这个传递是通过主上下文协调的，所以主上下文要保持“轻量”——只放任务清单和关键结论，不放具体代码。我一般会让每个子任务结束时输出一份简短的结构化总结，主上下文只保留这些总结。

3.3 effort 参数：质量和成本的调节旋钮

effort 这个词直译是“努力程度”，在 Claude Code 里它控制的是模型在单个任务上投入的推理资源。effort 越高，模型思考越充分、考虑的边缘情况越多，但消耗的时间和额度也越多。

这个参数的价值在于不是所有任务都值得高 effort。改一个变量名和设计一个复杂的状态机，需要的思考深度完全不同。我实测下来的经验值：

低 effort 不是“偷懒”，而是避免过度思考导致的画蛇添足。我遇到过让模型改个变量名，它顺手把整个函数的错误处理都重写了，结果引入了新 bug。后来把 effort 调低，它就老老实实只改名字。这个教训告诉我：匹配任务复杂度的 effort 才是最优解，不是越高越好。

4. 完整实操流程：从零跑通一个重构任务

4.1 环境准备与项目初始化

假设你还没装 Claude Code，我按实际步骤走一遍。不同系统略有差异，我以最常见的两种环境为例。

macOS 或 Linux 环境下，安装方式通常是包管理器或者官方提供的安装脚本。装完之后，进入你的项目根目录，执行初始化命令。这一步会生成一个初始的 CLAUDE.md 模板，你需要根据项目实际情况填充。

Windows 环境下要注意一个常见问题：路径和权限。有些安装方式对 64 位系统的兼容性有要求，如果遇到安装失败，优先检查系统版本和权限设置。另外 Windows 下的终端建议用 PowerShell 7 以上，老版本终端在输出长文本时可能截断。

初始化完成后，第一件事是验证模型能正确读取项目结构。我会让它执行一个简单任务，比如“列出 src 目录下所有的 React 组件文件，并说明每个组件的职责”。如果它能准确列出并且职责描述合理，说明项目上下文读取正常。如果它列错了或者漏了，说明 CLAUDE.md 里的目录约定没写清楚，需要补充。

4.2 编写第一版 CLAUDE.md 的实操要点

第一版不要追求完美，先覆盖最关键的约束。我的建议是从“最容易出错的地方”写起。回顾一下你平时 review 代码时最常打回的几类问题，把它们写进去。

比如我团队最常打回的是：用了 any 类型、异步没处理错误、组件里直接写业务逻辑。那第一版 CLAUDE.md 就重点写这三条。写的时候要具体，不要写“注意类型安全”这种废话，要写“禁止使用 any，不确定的类型用 unknown 配合类型守卫”。

写完第一版后，做一次对照测试：故意让它写一段违反约定的代码，看它会不会被 CLAUDE.md 拦住。比如我让它“写一个快速获取用户数据的函数”，如果它直接用了 any 并且没处理错误，说明约束没生效，需要检查 CLAUDE.md 的格式和位置是否正确。

注意：CLAUDE.md 的解析对格式敏感。用标准的 Markdown 标题和列表，不要用奇怪的缩进或特殊符号，否则可能被忽略。

4.3 用 Sub-agent 执行一个真实重构任务

我拿一个真实案例走一遍。任务背景：项目里有一个旧的 API 调用方式，散落在十几个文件里，现在要统一迁移到新的封装。

第一步，让主上下文做分析。我输入的任务描述是：“分析 src 目录下所有直接调用 fetch 的地方，输出文件路径、行号、调用的 URL 和当前的错误处理方式。”这个任务不需要改代码，只需要分析，effort 设成中。

它输出的清单我检查了一遍，确认没有遗漏。这一步很关键，因为如果分析阶段就漏了文件，后面迁移就会留下隐患。

第二步，拆分迁移任务。根据清单，我把迁移拆成三批：先改工具函数和类型定义，再改业务组件，最后改测试文件。每批作为一个 Sub-agent 任务。

第三步，逐个执行并验证。每批任务执行完后，立刻跑类型检查和测试。这里有个技巧：不要等所有批次都改完再验证，那样一旦出错很难定位是哪一批引入的。改一批、验一批，问题范围小，排查快。

第四步，处理边界情况。迁移过程中遇到两个特殊情况：一个是某个文件里的 fetch 带了特殊的 header，新封装默认不带；另一个是某个调用在 catch 里做了特殊处理，新封装的错误类型不一样。这两个都是分析阶段没覆盖到的，需要单独处理。这也说明分析阶段不可能百分百完整，执行阶段要保持警惕。

4.4 参数调节与成本控制

整个重构任务下来，我记录了一下 effort 的分配：分析阶段用中，迁移阶段用中，边界处理用高。总体消耗在可接受范围内。

成本控制的核心是避免无效的高 effort。我见过有人所有任务都开最高 effort，结果改个注释都要等半天，额度也烧得快。正确的做法是：先按经验值设一个档位，如果输出质量不够再往上调，而不是一上来就拉满。

另一个省额度的技巧是复用分析结果。分析阶段输出的清单和结论，在后续子任务里直接引用，不要让模型重新分析一遍。这既省额度，又保证一致性。

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

5.1 模型不遵守 CLAUDE.md 约定怎么办

这是最高频的问题。排查顺序如下：

先确认 CLAUDE.md 的位置对不对。项目层的必须在项目根目录，文件名大小写要完全匹配。我遇到过有人写成 claude.md，结果一直不生效，查了半天。

再确认格式。用标准的 Markdown，标题用 #，列表用 -。不要用 HTML 标签或者特殊符号。如果内容太长，考虑拆分到目录层，而不是堆在一个文件里。

最后确认约束的表述。否定式约束比肯定式更有效。“禁止使用 any”比“请使用明确的类型”效果好。因为模型对“禁止”这类硬约束的遵循度更高。

如果以上都对了还是不遵守，可能是任务描述本身和约束冲突。比如你让它“快速实现一个功能”，它可能为了“快速”而违反类型约束。这时候要在任务描述里明确“遵守项目约定优先于速度”。

5.2 Sub-agent 之间信息丢失怎么处理

Sub-agent 的上下文是独立的，信息不会自动共享。如果发现后面的子任务不知道前面的结论，说明主上下文没有正确传递。

解决方法是让每个子任务输出结构化的总结，主上下文只保留这些总结。总结要包含：做了什么、关键决策、遗留问题。不要放具体代码，代码放在文件里，总结里只放路径和行号。

我一般会要求子任务结束时输出一个固定格式的总结块，比如：

## 子任务总结 - 修改文件：src/api/client.ts - 关键决策：错误类型统一用 ApiError - 遗留问题：src/legacy/old.ts 暂未迁移

这样主上下文一眼就能看到状态，传递给下一个子任务时也不会丢信息。

5.3 任务执行到一半卡住或跑偏

卡住通常是因为任务描述太模糊，模型不知道下一步该干什么。这时候不要干等，直接中断，把任务描述改得更具体再重跑。

跑偏通常是 effort 设太高，模型开始“自由发挥”。比如你让它改一个函数，它把整个文件都重构了。这时候降低 effort，并且在任务描述里加上边界：“只修改指定的函数，不要改动其他部分”。

还有一个隐蔽的坑：任务描述里的歧义。比如“优化这个函数”，优化可以是性能优化、可读性优化、代码量优化，模型可能选了你不想的那个。所以任务描述要明确优化的目标，比如“在不改变行为的前提下，减少重复代码”。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑：CLAUDE.md 写太长。我一开始把整个开发规范都搬进去了，结果模型反而抓不住重点。后来精简到只保留最关键的十条约束，效果明显变好。规则不在多，在于每条都能被执行。

第二个坑：Sub-agent 拆得太细。有次我把一个任务拆成十几个子任务，结果光是协调它们之间的信息传递就花了很多时间，还不如不拆。拆分的粒度要匹配任务的复杂度，简单任务不需要拆。

第三个坑：忽略验证环节。有次迁移任务改完直接提交了，结果测试挂了才发现有个边界情况没处理。后来我强制自己每批改动后都跑一遍测试，虽然多花几分钟，但省下了回滚和排查的时间。

第四个坑：effort 一直用高档。刚开始觉得高档质量好，后来发现改简单东西时高档反而容易过度设计。现在我会根据任务类型动态调整，简单任务用低档，复杂任务才用高档。

6. 这套工作流的适用边界与扩展方向

说了这么多好处，也得讲讲它不适合什么场景。一次性脚本、探索性原型、没有明确规范的项目，用这套工作流反而累赘。因为写 CLAUDE.md 和拆 Sub-agent 都需要前期投入，如果项目本身就不稳定，投入产出比不划算。

它最适合的是有稳定规范、需要长期维护、多人协作的项目。这类项目里，前期投入的规范成本会被后续的每次任务摊薄，越用越划算。

扩展方向上，我最近在尝试把 CLAUDE.md 和团队的代码 review 清单打通——review 时发现的高频问题，直接沉淀成 CLAUDE.md 的约束。这样 AI 辅助和人工 review 就形成了闭环，规范越来越完善，AI 的输出也越来越稳定。

另外，Sub-agent 的拆分逻辑其实可以复用到其他 AI 辅助工具上。核心思想是通用的：复杂任务拆成可独立验证的单元，每个单元有明确的输入输出。这个思路不依赖具体工具，换个平台照样能用。

最后分享一个我最近的小发现：把 CLAUDE.md 里的约束按“硬约束”和“软建议”分开写，硬约束用“禁止/必须”，软建议用“建议/优先”，模型对硬约束的遵循度明显更高。这个区分看起来小，但实际效果差别挺大，你可以试试。