Fable Plan 是一个规划类技能,用于把已经获得的发现证据转化为可执行的变更策略,明确依赖关系、风险边界、验收证明和集成归属。其核心理念是:计划不是要编辑的文件清单,而是一组让实现足够清晰、可安全执行的决策;规划者应消除架构不确定性、暴露顺序约束、定义“完成”的含义,并只在能够独立推理和验证的部分之间拆分工作。
适用场景 当任务跨越多个文件或组件、引入新契约;需要迁移、模式变更、公共 API 变更或跨包重构;实现需要排序或回滚推理;并行工作者可能有用但必须设计归属与集成;需求已理解但尚未分解为可验证工作时,应启用该技能。
不适用场景 当关键事实仍然未知(应回到发现/研究阶段);变更确实局限于一个明显编辑且有明确验收(应走执行);当前任务是先在测试中复现行为(应走 TDD)时,不应使用。
变更分类 分解前先分类变更类型,不同类型关注点不同:边界行为关注验收与回归面;跨模块功能关注契约与集成点;重构关注不变量保持与分阶段兼容;数据/模式迁移关注前向/后向兼容与回滚;公共 API/CLI 关注兼容性、版本化与文档/测试;依赖升级关注行为差异与传递风险;安全敏感关注信任边界与失败关闭行为;发布/分发关注制品边界与外部验证。
规划流程 阶段一:重述契约。记录请求的结果、非目标、已建立的证据、不得回归的外部可见行为,以及未解决项及其为何不阻塞。若存在阻塞性未知,停止并回到发现/研究。 阶段二:映射变更图。识别涉及组件、组件间契约、数据/状态转换、迁移或兼容边界、共享集成热点、生成制品及其来源、验证面。用依赖关系而非仅编号任务来表示顺序。 阶段三:选择分解接缝。一张卡应有一个连贯的变更理由和一个清晰的验收故事。不要求文件互斥作为通用规则:两张卡可以在明确归属/顺序下顺序触碰同一集成文件;反之,不同文件的两张卡若改变同一共享不变量或契约,也可能不宜并行。 阶段四:风险优先规划。尽量把高不确定性或不可逆决策提前,例如先证明迁移形态再做广泛数据重写,先证明兼容适配器再删除旧路径,先证明第三方 API 契约再接入所有调用点,在风险运行时变更前引入可观测性。 阶段五:定义每张卡。每张卡须写明目标与用户可见效果、所属范围与禁止范围、依赖/前置条件、仅在约束正确性时给出的实现说明、验收证据/命令、失败代价高时的回滚或恢复说明、交接/集成期望。 阶段六:定义集成归属。明确由谁/什么证明组合结果;跨卡行为不能只依赖各工作者本地通过。 阶段七:以失败检验计划。追问:卡 2 在卡 1 落地后失败怎么办?迁移期间新旧格式能否共存?是否有不可逆步骤?回滚是否保留数据/契约?测试能否检测主要回归?并行执行是否产生合并或语义冲突?
决策规则 架构未知走发现;外部契约未知走研究。有可测试契约的行为变更,第一张实现卡应走 TDD。只有当依赖、归属、共享不变量和集成点使并发安全时才并行。新旧调用方或持久化数据可能共存时,优先分阶段兼容而非一次性切换。若一张卡无法列出可证伪的验收证据,则尚未就绪。若规划产生超过约 5 张紧密耦合的卡,考虑里程碑边界或不同架构,而非机械拆分。生成文件属于改变其来源/生成器的那张卡,不作为独立手工编辑。
不变量 每张卡都可追溯到需求或必要的使能约束;执行卡中不隐藏阻塞性架构未知;验收检查证明行为而非仅文件存在;集成验证有归属;破坏性/不可逆步骤有明确保障或回滚推理;并行由依赖分析证明而非仅文件数量。
失败分类 隐藏依赖:卡意外需要另一组件,应更新依赖图,不得让执行悄然扩大范围。虚假独立:卡触碰不相交文件但共享一个不变量/契约,应串行或定义兼容接缝。验收薄弱:检查可通过而行为仍可能损坏,执行前强化验收条件。迁移风险:生产中新旧状态可共存但计划假设原子切换,需兼容、回填或分阶段推出。范围爆炸:卡不断发现架构工作,应停止并回到发现/规划重划边界。
反模式 一文件一卡;即使顺序集成更安全仍要求文件互斥;仅凭“文件不同”就并行;验收仅写“测试通过”而不指明相关行为;把迁移/回滚藏在实现叙述中;把文档/生成输出当作独立卡;产出无依赖模型的长任务清单;在执行证据出现前逐行过度指定代码。
工作卡模板 卡:<结果>;理由:<需求/风险>;依赖:;所属:;不得改变:;行为/不变量:;实现约束:;验收证据:;回滚/恢复:;集成交接:;可并行于:。
完成标准 规划在以下情况完成:阻塞性未知已消除;依赖/顺序约束明确;卡连贯且以行为而非任意文件切片为界;每张卡有可证伪验收证据;相关迁移/兼容/回滚问题已处理;若提出并行,有明确语义归属和集成证明。
渐进资源 深度分解指南:references/risk-and-dependency-decomposition.md;现有分解规则:references/decomposition-rules.md;模板:templates/work-card.template.md;示例:examples/multi-file-migration-plan.md。