第三课：编排一场大重构
用你的 KMP 个人页做实战

≈18 分钟 · AI 时代战略型工程师 · 课程 0003 · 2026-06-14
前置：第一课·委派阶梯 · 第二课·可执行规格 · 参考：术语表 · 能力速查表

这一课你真正要学的东西

你要做的不是"让 AI 改代码"，而是设计一条让多个 Agent 安全完成 256 文件 / 4 万行重构的流水线，并且自己当总指挥。这是第一课的③④级和第二课的规格冻结第一次合体落到真实任务上。学完你应该能回答：一个大到单 Agent 装不下的重构，怎么拆、谁来 review、怎么保证不改坏、Claude Code 和 Codex 各干什么。

⚠ 重要：本课不直接动你的代码。它的产物是一份"如何执行"的心智模型 + 一份待你确认的 HTML 方案。动手前必须先过你这一关。

第一性原理：为什么不能"一把梭"

直觉做法是开一个强力会话说"把这个项目重构成 MVI、复用基建、去重、补日志"。这会失败，原因有三，全部来自你的真实勘察：

墙一 · 上下文装不下
256 文件、+43k 行。单个 Agent 读完就没余量推理了，会丢细节、产生幻觉式改动
墙二 · 无验收无法委派
"统一架构"不是可检查的标准。不先定义"统一成什么样"，Agent 会编 5 套各自合理的方案（你现在的混乱正是这么来的）
墙三 · 盲目并行会撞车
Talk 和 Story 共用同一个 ViewModel、外部事件/分页 generation 共享——两个 Agent 同时改这俩 Tab 必然互相覆盖

"默认状态下的 LLM 是不知疲倦的战术型程序员——倾向复制代码块而非抽象共性。人的战略设计能力是系统复杂度的天花板。" — Complexity Is the Ceiling

正确形态是 pipeline（流水线）：把不可逆的大改动拆成一串"可验证的小关卡"，每关有明确产物和验收，关卡之间用人或对抗 Agent 把门。这正是 Claude Code 的 Dynamic Workflows 的默认结构（详见术语表 ultracode），但更重要的是它背后的思路，工具只是承载。

为你的任务设计的五关流水线

你已经无意识地做对了第一步——你让我"先勘察再设计"。下面是完整的五关，每关我标注了用哪个工具、谁把门、验收是什么。

关0 盘点
Agent 只读→ 关1 方案冻结
你拍板→ 关2 并行改造
worktree 隔离→ 关3 对抗 review
独立挑刺→ 关4 真机验证
你的安全网
0
盘点（只读，已完成）
👤 人把门 🤖 Agent 执行 Claude Code · Explore（只读）
做什么
派只读 Explore Agent 摸清现状，绝不改动。
把门
你看勘察报告，确认事实无误。
产物
现状事实清单（已交付，含 5 个 Tab、4 套设计思想、点赞各写各的、评论面板全是 STUB 等）。
为何必须
第二课原则——方案必须建立在真实代码上，否则悬空。
1
方案与规格冻结（你最该花时间的地方）
👤 你拍板（spec gate） Claude Code · Opus / Fast Mode
基于盘点，产出一份 HTML 方案。它不只是给你看的文档，它就是这场重构的 SPEC（第二课的五组件在这里全部具象化）：

· 黄金样本：选一个 Tab（建议 Savior，它日志/注释最完整）作为"标准 MVI Tab"的参考实现，其余向它对齐。
· 验收标准：可检查的统一规约——MVI 分层文件结构、日志 tag 规则（页面 tag + 二级 tab tag）、必须复用的基建清单。
· 反例：明确禁止——不再各写各的点赞、不再 STUB 评论面板。
· 改动单元清单 + 依赖图：哪些能并行、哪些必须串行（Talk/Story 耦合必须当成一个单元）。

把门
你确认 HTML 方案 = spec gate。这是你要求的"先方案后动手"，本质是冻结规格。
产物
REFACTOR_PLAN.html + 机器可读的 units.md（改动单元清单）。
2
逐单元改造（并行，但带护栏）
🤖 Agent 执行（并行） Claude Code · worktree Codex · 批量机械任务
每个改动单元 = 一个 Agent 任务，输入固定三件套：冻结的方案 + 黄金样本 Tab + 该单元的边界。先做"共用层"（抽出统一的点赞组件、FooterState、LoadStateHost、复用 BoxCommentPanel/CommentDiggView），再让各 Tab 改用共用层——这个顺序不能反。

工具
并行用 worktree 隔离（claude -w，每个 Tab 一个工作目录，互不踩文件）；机械性强的批量改（补日志 tag、套用模板）适合丢给 Codex（同等工作省 token、Goal Mode 可长跑）。
把门
每个单元改完先过关 3，不直接进主干。
护栏
Talk/Story 当一个单元；StoryVideo 的 JustWatched 逻辑单独标注高风险。
3
对抗式 review（防改坏的核心）
👤 两路都过才放行 Codex review · @codex review Claude · 对照冻结方案
每个单元改完，派独立的 review Agent，任务是"挑刺、证明它改坏了"而非"看起来对吗"。两路并行：

· Codex review：@codex review 抓回归 bug、行为变化（它只报 P0/P1，噪音低）。
· Claude review：对照冻结方案逐条核对——真用了基建吗？真去重了吗？MVI 分层对吗？日志 tag 对吗？

把门
两路都过 + 编译通过，才进下一关。
为何对抗
让改代码的 Agent 自己 review 自己等于没 review。独立 + 唱反调才能抓出"看起来对、实际改坏"的改动。
4
真机验证（你的安全网，决定敢委派的层级）
👤 三项全过才合入 Claude Code · device-control .a2k/ 截图体系
你有别人没有的东西：完整验证设施。每个单元过 review 后跑真验证：

· 编译：./gradlew :biz:community:community-impl:compileFanqieDebugKotlin
· 截图测试：Native vs KMP 同账号同路径比对（你已有的 .a2k/ 体系）。
· remoteX 装机 + device-control 控设备 + 看日志：确认每个子 Tab 能展示数据。

把门
三项过，单元合入。任一不过，退回关 2 带着失败证据重做。
根本原因
这一关是你敢上③④级的根本原因：没有它，大体量委派就是赌博。
ⓘ 不可逆动作永远在人或验证之后。每一关都有"谁把门"——合入主干这个不可逆动作，只发生在关 4 三项全过之后。
一句话记住整条线：盘点(看) → 冻结规格(你拍板) → 并行改(护栏隔离) → 对抗review(独立挑刺) → 真机验证(安全网)。每一关都有"谁把门"，不可逆的合入动作永远在人或验证之后。

Claude Code × Codex：这个任务里怎么分工

你两个工具都有，社区验证过的分工是"Claude 想，Codex 做"（能力表·分工心法）。映射到本任务：

关 Claude 主力 理由
关 0 盘点 Claude Code 需要在大代码库里推理"哪些是重复、哪些是基建"——推理活
关 1 方案 Claude Code 架构设计、识别 Talk/Story 耦合这类深坑——最吃推理质量
关 2 改造 分工：共用层抽象 Claude，机械套模板/补日志 Codex 抽象要品味用 Claude；批量补 tag、套 MVI 模板这种重复劳动 Codex 更省更快
关 3 review 两个都上（对抗）Claude Codex Codex 的 @codex review 抓回归是独有强项；Claude 对照方案核对一致性。两个独立视角比一个强
关 4 验证 Claude Code（驱动 device-control） 需要根据日志判断、失败时回到推理——闭环收口

你作为总指挥，实际要敲什么

不要自己写 1000 行编排脚本——你的杠杆在把门和拍板，不在写 JS。实际操作是分关推进，每关一句自然语言指令：

Claude Code · 指令话术 
# 关 1：让 Claude 出方案（同步结对，你来回打磨）
基于勘察报告，产出 REFACTOR_PLAN.html：定义标准 MVI Tab（以 Savior 为黄金样本）、
统一日志 tag 规则、必须复用的基建清单、改动单元清单与依赖图（标出 Talk/Story 必须
同改、StoryVideo JustWatched 高风险）。先给我确认，不要动代码。

# 关 2-4：方案确认后，对每个单元（举例第一个共用层单元）
用 worktree 起一个隔离会话，按 REFACTOR_PLAN.html 抽出统一点赞组件并复用
CommentDiggView；改完先自测编译，再交给独立 review，最后跑截图测试。
任一关不过就停下报告我，不要硬合入。

# 关 3 的 Codex 一路（在 PR 上）
@codex review   # 抓回归
@codex fix it    # 如确认是真问题再让它修

体量很大、单元很多时，才把"对每个单元重复跑 2→3→4"这件事交给 Dynamic Workflows 自动 pipeline（ultracode）。但第一版建议手动跑通 2-3 个单元，确认流水线靠谱了再自动化——否则你是在自动化一个还没验证的流程。

自测（先回忆，再点选）

1. 大体量重构最不该采用的委派形态是哪种？

一把梭会同时撞上三堵墙：上下文装不下 43k 行、无验收标准导致编出多套方案、盲目并行撞车（Talk/Story 共用 ViewModel）。pipeline 才是正解。

2. 你要求的"先出 HTML 方案再动手"，本质是什么？

HTML 方案就是第二课的 SPEC 具象化——黄金样本、验收标准、反例、单元依赖图全在里面。你确认它 = spec gate，之后所有 Agent 以它为 source of truth。

3. 为什么 review 必须由独立 Agent 来做？

改代码的 Agent 带着"我的实现是对的"先验，自审等于没审。独立 + 唱反调（证明它改坏了）才能抓出"看起来对、实际回归"的改动——这正是你"怕改坏"的解药。

4. 这个任务敢上③④级委派的根本依据是什么？

第一课原则：敢委派的层级由验证手段决定，不由工具能力决定。你的编译+截图+device-control看日志构成安全网——没有它，并行委派只是更快地制造你看不过来的隐患。

下一步（动手前的唯一一关）

我们现在就做：产出关 1 的 HTML 方案

勘察已完成。下一步我会基于真实事实，派 Agent 产出 REFACTOR_PLAN.html——你要求的那份"先确认的方案"。在我动手前，你只需要拍板三件事（我会用提问的形式问你）：

  1. 黄金样本 Tab 选哪个（我倾向 Savior，日志注释最全；但 Bookshelf 是唯一有独立 Reducer 的，要不要它的分层）
  2. 四个诉求的执行顺序（我倾向：先复用基建+抽共用层 → 再统一 MVI → 最后补日志注释，因为前者改完结构稳了，后者才不白补）
  3. 第一批先试点几个单元跑通流水线，再决定要不要 Workflows 自动化

想清楚这三点，或者直接说"按你的建议来"，我就去出方案。

引用文献

🧠背诵区

点卡片翻面。记的是能用的判断核心，不是定义。

闪卡 1 / 第一性原理
大体量不可逆改动为什么不能"一把梭"丢给一个强力会话？
翻面
三堵墙：①上下文装不下（读完就没余量推理，会幻觉）；②无验收无法委派（"统一架构"不可检查，会编出 5 套各自合理的方案）；③盲目并行会撞车（共享文件互相覆盖）。
闪卡 2 / 正确形态
替代"一把梭"的正确编排形态是什么？一句话说清结构。
翻面
pipeline 流水线：把不可逆大改拆成一串"可验证的小关卡"，每关有明确产物和验收，关卡之间用人或对抗 Agent 把门。工具（Workflows）只是承载，思路才是核心。
闪卡 3 / 你的角色
这场重构里你（总指挥）真正要做的不可委派的事是什么？
翻面
设计流水线、在关 1 拍板冻结方案、设把门规则、做关 4 真机验证当安全网。审的是"编排逻辑"而非"每行代码"——不接受 agent 给的方案，用对系统的真实理解逼问、修正它。
⏱ 间隔复习：明天扫一遍，3 天后再来。交织：翻一张第二课「可执行规格」的旧卡——关 1 的"方案冻结"就是给整场重构写一份冻结的 SPEC，验收标准从那来。
🗣复述区

能讲清楚，才是真懂——比能回忆高一层。

复述任务
用一段话向同事讲清楚：面对一个 256 文件、4 万行的大重构，你为什么先设计一条五关流水线、而不是直接开干？这体现了什么战略思路？
参考表述
因为大体量、不可逆的改动一把梭必然失败：单 agent 上下文装不下会幻觉，"统一架构"没有可检查的验收标准没法委派，盲目并行会在共享文件上撞车。所以正确做法是把它拆成一条流水线——盘点、方案冻结、并行改造（worktree 隔离）、对抗 review、真机验证——每一关产物明确、验收可查，关卡之间用人或对抗 agent 把门。我的价值不在写代码，而在设计这条管线、在方案关拍板、在终点验证；agent 负责在我画好的安全边界内并行执行。这就是"管理 agent 即战略活动"的实操形态。

讲不顺的地方就是还没真懂的地方 —— 发给我，我帮你补上。

有任何不清楚的，直接问我——比如"为什么共用层要先于各 Tab 改""Workflows 和我手动跑有什么区别""Talk/Story 那个耦合具体怎么处理"。拍板上面三件事后，我就去产出待你确认的 HTML 方案。