可复现代码迁移：用可审查 Playbook 约束长任务方差

先说结论

长迁移的不稳定，往往在第一版计划里就开始累积。Playbook 的价值不是让 LLM 变成确定性程序，而是把历史上验证过的顺序、失败模式和取舍变成可人工审查的约束，让后续计划少走几条看似合理、实际方差很大的岔路。

为什么原始记忆不够

同一输入重复运行，Agent 可能选择不同文件、不同重构顺序和不同依赖处理方式。单步差异不大，经过数百个相互依赖的决定后，最终状态会明显分叉。把所有历史片段直接塞进向量库也没有自动解决这个问题：一次性的仓库怪癖可能被误当成通用规律，大量碎片又很难让专家逐条复核。

核心机制

Playbook 的输入不是 Agent 的事后总结，而是可追溯的迁移工件：提交历史与 diff 说明改了什么，错误日志说明哪里失败，解决策略说明如何恢复，决策理由说明为什么选这条路径。生成过程再做四件事：

1. 按迁移阶段和问题类型聚类，不按对话顺序堆材料。
2. 区分跨多个仓库反复出现的模式与一次性例外，并保留适用条件。
3. 把模式组织成章节、步骤、前置条件、失败处理和验证，而不是松散的“经验条目”。
4. 交给领域专家审查、删改和定版；后续 Agent 使用的是已批准版本，不是持续漂移的原始记忆。

这样做重点约束规划阶段：任务定义说明“迁到哪里”，Playbook 说明“通常按什么顺序、遇到什么信号时切换方案”。它缩小选择空间，但不能替代仓库自己的测试、owner 判断和迁移验收。

和 Zero-to-AI 的日常开发怎么接上

本站不需要先建设大规模知识系统。对一次依赖升级或目录迁移，可以从一页 Markdown 开始：固定基线与目标版本，列出已观察 diff、首个错误、有效修法、被拒方案及理由，再写成顺序明确的检查表。下一次相似迁移先复制这份 Playbook，经当前仓库的调用者和测试校正后再执行。

关键是保留“为什么”。只有命令没有失败信号，Agent 无法判断何时重试、何时停止；只有成功补丁没有被拒方案，下一轮还会重新试错。历史多数也不等于正确，平台升级后必须重新审查旧结论。

一个低成本实验

输入： 一个包含 3 个相似小包的练习仓、一次已由人工完成的版本升级，以及该过程的 diff、错误日志和决策记录。

步骤：

1. 从历史工件写一页 Playbook，明确前置条件、执行顺序、常见失败和验证命令，由一位熟悉依赖的开发者审阅。
2. 固定模型、仓库快照和预算，分别对两个未迁移小包运行“仅任务说明”和“任务说明 + Playbook”。
3. 比较首版计划的步骤集合与顺序、无效尝试数、最终语义 diff 和测试结果。
4. 把只在单个包出现的例外留在运行记录中，不立即升级为通用规则。

成功证据： Playbook 组的计划更一致，能提前避开历史中已知失败；两个小包仍分别通过自己的原验收，且专家能从 Playbook 追溯每条关键建议的历史依据。

停止线： 历史样本只有一次、关键日志缺失、Playbook 未经领域审查，或目标版本已经改变；此时只能把它当候选草稿，不能据此批量迁移。

常见误区

• “重复最多的做法就是最佳实践”：多数可能只是共同遗留错误，仍需专家纠正。
• “Playbook 能保证相同 diff”：它减少规划方差，不消除模型、环境和仓库差异。
• “把所有经验都收进去更安全”：罕见怪癖会污染主路径，例外应带适用条件单列。

原文与证据边界

AWS 报告，用 77 个仓库生成的 Playbook 比 10 个仓库版本更具体；其 TD + Playbook 条件在三种 LLM judge 的六项比较中提升 4.93%–15.79%，其中五项达到其统计显著标准。这些是 AWS Transform custom 的内部实验，本站没有取得迁移仓库、judge 提示、评分数据或生成流水线，未复现一致性提升。本文实验只检验小样本计划与结果，不外推到企业级批量迁移。

本文是原创中文实践解读，不是逐句翻译。阅读英文原文。