fable-plan

Fable Plan

将有依据的证据转化为可执行的变更策略，明确依赖关系、风险边界、验收证明和集成责任。

使命

计划不是一份待修改文件清单，而是一组决策，让实现过程足够简单，从而可以安全执行。

规划者应消除架构上的不确定性，明确顺序约束，定义“完成”的标准，并且仅在各部分确实能够独立推理和验证时，才将工作拆分。

何时启用

• 任务涉及多个文件／组件，或引入新契约；
• 需要迁移、架构变更、公共 API 变更或跨包重构；
• 实现需要考虑执行顺序或回滚；
• 并行工作者可能有所帮助，但必须设计好职责归属／集成方式；
• 已理解需求，但尚未将其分解为可验证的工作。

何时不要启用

• 仍有关键事实未知（fable-discover／fable-research）；
• 变更确实只涉及一处明显的修改，且验收标准清晰（fable-execute）；
• 当前任务是复现测试中的某种行为（fable-tdd）。

变更分类

分解前先分类。

变更类型	主要规划关注点
范围明确的行为变更	验收和回归范围
跨模块功能	契约＋集成点
重构	保持不变量＋分阶段兼容
数据／架构迁移	向前／向后兼容＋回滚
公共 API／CLI	兼容性＋版本管理＋文档／测试
依赖升级	行为差异＋传递风险
安全敏感变更	信任边界＋失败时拒绝访问
发布／分发	产物边界＋外部验证

规划流程

阶段 1 — 重述契约

记录：

• 预期结果；
• 非目标；
• 已确立的证据；
• 不得退化的外部可见行为；
• 尚未解决的事项及其不会阻塞工作的原因。

如果仍有阻塞性未知项，请停止并返回探索／研究阶段。

阶段 2 — 绘制变更图

识别：

• 涉及的组件；
• 组件间的契约；
• 数据／状态转换；
• 迁移或兼容性边界；
• 共享集成热点；
• 生成产物及其来源；
• 验证范围。

将执行顺序表示为依赖关系，而不只是编号任务。

阶段 3 — 选择拆分边界

每张任务卡应有一个连贯的变更原因和一套明确的验收方案。

不要把文件互不重叠作为普遍要求。如果职责和顺序明确，两张任务卡可以依次修改同一个集成文件。反之，即使两张卡修改不同文件，如果它们变更同一个共享不变量或契约，也可能不适合并行执行。

阶段 4 — 优先规划风险

尽可能提前处理不确定性高或不可逆的决策：

• 大规模重写数据前，先验证迁移方案；
• 删除旧路径前，先验证兼容性适配器；
• 接入所有调用点前，先验证第三方 API 契约；
• 进行高风险运行时变更前，先引入可观测性。

阶段 5 — 定义每张任务卡

每张卡都必须说明：

• 目标和用户可见的效果；
• 负责范围和禁止涉及的范围；
• 依赖关系／前置条件；
• 仅在影响正确性时提供实现说明；
• 验收证据／命令；
• 失败代价较高时的回滚或恢复说明；
• 交接／集成预期。

阶段 6 — 明确集成责任

明确由谁／什么来证明组合后的结果。对于跨卡行为，工作者各自通过验证还不够。

阶段 7 — 根据失败情形检查计划

询问：

• 如果任务卡 1 合并后任务卡 2 失败，会怎样？
• 迁移期间，新旧格式能否共存？
• 是否有不可逆的步骤？
• 回滚能否保留数据／契约？
• 测试能否检测主要回归？
• 并行执行是否会引发合并冲突或语义冲突？

决策规则

• 架构未知时 → fable-discover；外部契约未知时 → fable-research。
• 如果行为变更具有可测试的契约 → 通过 fable-tdd 路由第一个实现卡片。
• 只有当依赖关系、所有权、共享不变量和集成点确保并发安全时，才并行执行。
• 如果新旧调用方或持久化数据可能共存，优先采用分阶段兼容方案，而不是一次性替换。
• 如果卡片无法列出可证伪的验收证据，则尚未准备就绪。
• 如果规划产生了 5 张以上紧密相互依赖的卡片，应考虑划分里程碑边界或采用不同的架构，而不是机械地继续拆分。
• 生成文件应归属于修改其源文件或生成器的卡片，而不是作为独立的手动编辑项。

不变量

• 每张卡片都能追溯到一项需求或必要的使能约束。
• 不得将阻塞性架构未知项隐藏在执行卡片中。
• 验收检查应证明行为，而非仅证明文件存在。
• 集成验证必须有明确负责人。
• 破坏性或不可逆步骤必须明确说明防护措施或回滚方案。
• 并行执行必须由依赖分析证明合理，而不能仅依据文件数量。

失败分类

隐藏依赖

卡片意外需要另一个组件。更新依赖关系图；不要让执行过程悄然扩大范围。

虚假独立

卡片涉及互不重叠的文件，但共享一个不变量或契约。应按顺序执行，或定义兼容性接缝。

验收不足

拟定的检查可能通过，但行为仍然有问题。执行前应强化验收条件。

迁移风险

新旧状态可能在生产环境中共存，但计划假设可以原子式切换。应增加兼容机制、数据回填或分阶段发布。

范围膨胀

卡片不断发现架构工作。应暂停，返回发现或规划阶段，并重新划定边界。

反模式

• 每个文件一张卡片；
• 即使顺序集成更安全，也要求卡片涉及互不重叠的文件；
• 仅仅因为“涉及不同文件”就并行执行；
• 验收标准只写“测试通过”，却未指出相关行为；
• 在实现说明中隐藏迁移或回滚内容；
• 将文档或生成输出视为独立卡片，尽管它们属于同一项行为变更；
• 生成冗长的任务列表，却没有依赖模型；
• 在执行证据尚不存在之前，逐行过度规定代码。

工作卡片模板

Card: <outcome>
Why: <requirement/risk>
Depends on:
Owns:
Must not change:
Behavior/invariant:
Implementation constraints:
Acceptance evidence:
Rollback/recovery:
Integration handoff:
Parallel-safe with:

完成标准

满足以下条件时，规划即告完成：

• 已消除所有阻塞性未知项；
• 已明确依赖关系和顺序约束；
• 卡片按行为划分，边界合理，而非任意按文件切分；
• 每张卡片都有可证伪的验收证据；
• 在相关情况下，已处理迁移、兼容性和回滚问题；
• 如提出并行工作，已明确语义所有权，并提供集成证明。

渐进式资源

• 深入了解拆解指南：references/risk-and-dependency-decomposition.md
• 现有拆解规则：references/decomposition-rules.md
• 模板：templates/work-card.template.md
• 示例：examples/multi-file-migration-plan.md