implementation-approach

# 实现策略选择框架（元认知方法） ## 元认知策略选择流程 ### 阶段 1：决策充分的现状分析 **核心问题**：“现有实现是什么样的？” #### 分析框架 ```yaml 架构分析: 职责划分、数据流、依赖关系、技术债务 实现质量评估: 代码质量、测试覆盖率、性能、安全性 历史背景理解: 现有形态的合理性、过去决策的有效性、约束变化、需求演变 ``` #### 元认知问题清单 - 该实现的真正职责是什么？ - 哪些部分是业务本质，哪些源于技术约束？ - 从代码中看不出哪些依赖关系或隐含前提？ - 当前设计带来了哪些收益和约束？ 当另一项现状事实无法改变职责、复用方式、方案有效性、总体复杂度、契约或验证结果时，停止分析。 **完成依据**：已检查的路径、观察到的架构/数据流事实、已知约束、标注为推断的历史合理性推断，以及可能改变策略选择的未知项。 **转换条件**：当每一项与策略相关的论断都已被观察到、附带证据明确推断，或记录为未知项时，进入下一阶段。 ### 阶段 2：设计收敛 **核心问题**：“能交付当前所需结果的最小设计是什么？每一项超出该设计的追加内容，各由什么依据支撑？” 在探索实现策略之前，按顺序完成以下步骤： 1. **现有职责基线**：通过现有职责，构建能交付当前结果的最简端到端路径。明确的需求和已接受的决策具有约束力；建议性的机制仍属候选项。 2. **依据核验**：用当前需求、已验证的约束、观察到的范围内问题以及有依据支撑的重大风险来检验该路径。只保留那些可能改变已选定设计的未满足条件。 3. **有针对性的比较**：针对每一项未满足条件，在增加设计增量之前，先测试复用、从现有数据派生、按需计算，或由当前调用方或边界承担职责等方案。按在用户决策、设置、模式、概念、输出、持久状态、实现路径、用户体验、运行时、实现、测试、文档和维护等存在实质差异的维度，比较各可行方案的总体复杂度。选择满足该条件且总体复杂度最低的方案。 4. **削减检验**：移除每一项提议的追加内容，并重新检验其所对应的条件。仅当被确认的结果、必要边界或必要证明因此无法满足时，才保留该追加内容。 候选路径和被否决的追加内容仍属于当前分析。需长期保留的输出是**已选定设计**：完整的选定路径，加上每项设计增量的依据，以及移除该项后会失效的条件。只有已接受的 ADR 可以将备选方案作为决策历史保留。实现时使用同样的收敛检验方式，无需产出单独的产物。 **完成依据**：一份完整的已选定设计；每项设计增量均说明其当前依据、设计增量更小的方案为何不足，以及削减检验的结果。 **转换条件**：当每一项支撑性论断都已被观察到、附带证据明确推断，或记录为未知项时，进入下一阶段；将阻塞下一步的未知项转化为继续所需的具体、可验证依据要求。仅当未知项要求变更已确认的成果、目标状态需求或非目标，或需要不可逆操作授权时，才与用户交互。 ### 阶段 3：策略探索与创建 **核心问题**：“在确定 before -> after 时，应参考哪些实现模式或策略？” #### 策略发现流程 ```yaml 调研与探索: 优先参考仓库中的既有模式；其次是与已解析依赖版本匹配的官方文档；再次是维护良好的开源实现；文献/博客仅用作补充性备选方案，并标注为非权威来源 创造性思考: 策略组合、基于约束的设计、阶段划分、扩展点设计 ``` #### 参考策略模式（鼓励创造性组合） **遗留系统处理策略**： - Strangler 模式：通过分阶段替换实现渐进式迁移 - Facade 模式：通过统一接口隐藏复杂性 - Adapter 模式：与现有系统之间的桥接 **新开发策略**： - 功能驱动开发：优先交付用户价值的垂直实现 - 基础驱动开发：优先保证稳定性的自底向上构建 - 风险驱动开发：优先处理风险最大的要素 **集成/迁移策略**： - Proxy 模式：透明的功能扩展 - Decorator 模式：对现有功能的分阶段增强 - Bridge 模式：通过抽象获得灵活性 **完成依据**：当决策并非显而易见时，至少提出两个可行的候选方案，每个候选方案都需对应到其所满足的观察到的约束，以及未解决的约束。 **转换条件**：当各候选方案都针对同一约束集合具备可比性时，进入下一阶段。 ### 阶段 4：风险评估与控制 **核心问题**：“将其应用于现有实现会产生哪些风险？哪种控制措施能在保留验证与回滚能力的同时，可衡量地降低发生概率或影响程度？” #### 风险分析矩阵 ```yaml 技术风险: 系统影响、数据一致性、性能下降、集成复杂度 运营风险: 服务可用性、部署停机、流程变更、回滚流程 项目风险: 进度延迟、学习成本、质量达成度、团队协作 ``` #### 风险控制策略 ```yaml 预防措施: 分阶段迁移、并行运行验证、集成/回归测试、监控设置 事件响应: 回滚流程、日志/指标准备、沟通机制、服务持续运行流程 ``` **完成依据**：每项重大风险都具备发生概率/影响程度的依据、一项预防或遏制控制措施，以及一个验证点。 **转换条件**：当每项高影响风险都已有控制措施或阻塞性上报时，进入下一阶段。 ### 阶段 5：约束兼容性验证 **核心问题**：“该项目的约束条件是什么？” #### 约束清单 ```yaml 技术约束: 库兼容性、资源容量、强制性要求、数值目标 时间约束: 截止日期/优先级、依赖关系、里程碑、学习周期 资源约束: 团队/技能、工时/系统、预算、外部合约 业务约束: 上市时机、客户影响、法规合规 ``` **完成依据**：每项约束都已被观察到、推断出，或标记为未知；每一项可能使某候选方案失效的未知项，都需明确指出继续所需的具体、可验证依据。 **转换条件**：当剩余的未知项不会改变有效候选方案集合，或由用户予以解决时，进入下一阶段。 ### 阶段 6：实现方案决策 在满足所有硬性约束和当前需求的前提下，选择过渡风险最低、验证延迟最小的方案。仅在需求覆盖度、兼容性和风险控制三者相当时，才将生命周期成本和实现工作量用作决胜因素。 #### 垂直切片（功能驱动） **特征**：按功能单元跨所有层进行垂直实现 **适用条件**：功能间依赖度低、输出为用户可用形式、需要跨所有架构层进行变更 **验证方式**：每个功能完成时交付终端用户价值 #### 水平切片（基础驱动） **特征**：按架构层分阶段构建 **适用条件**：基础系统稳定性重要、多个功能依赖共同基础、逐层验证有效 **验证方式**：所有基础层完成后进行集成运行验证 #### 混合方案（创造性组合） **特征**：根据项目特点灵活组合 **适用条件**：需求不明确、需要按阶段变更方案、从原型验证过渡到完整实现 **验证方式**：当该阶段产出终端用户可操作的行为时分配 L1；当该阶段产出可测试的内部行为或契约时分配 L2；仅当该阶段产出构建期结构、尚无可运行行为时才分配 L3 对于混合方案，为每个阶段分配一个明确的 L1/L2/L3 验证等级和可观测的完成结果。 **完成依据**：一个已选定的方案，其阶段边界、集成点，以及每个阶段的验证结果。 **转换条件**：当所选方案覆盖全部硬性约束、其风险均已配备控制措施时，进入文档记录阶段。否则返回候选探索（阶段 3）；若阶段 4-5 的结果改变了已选定设计或其依据，则返回设计收敛（阶段 2）。 ### 阶段 7：决策依据文档化 在设计文档或规划交接文档中返回以下结构： ```yaml implementationApproachDecision: observedConstraints: [<约束 + 依据>] inferredConstraints: [<约束 + 依据与推断>] unknowns: [<未知项 + 所需依据或决策>] selectedApproach: <vertical | horizontal | hybrid 方案说明> selectionRationale: <硬性约束覆盖度、兼容性、风险控制及总体复杂度依据> addedDesignSurface: [<设计增量 + 当前依据 + 设计增量更小的方案为何不足 + 削减检验结果>] phaseVerification: [<阶段 + L1/L2/L3 + 可观测的完成依据>] ``` 候选方案及否决理由仍属于当前分析，除非已被接受的 ADR 将其作为决策历史予以保留。 **完成依据**：所选方案及每项设计增量，均可追溯至一项观察到的约束、已接受的推断，或已解决的价值边界决策。 ## 验证等级定义 各任务完成验证的优先级： - **L1：功能运行验证** - 作为终端用户功能可运行（例如：用户可以执行搜索并获得结果） - **L2：测试运行验证** - 已新增测试并通过（例如：类型定义测试） - **L3：构建成功验证** - 无编译错误（例如：接口定义） **优先级**：按可验证性重要程度排序，L1 > L2 > L3 ## 集成点定义 根据所选策略定义集成点： - **基于 Strangler**：每个功能在新旧系统之间切换时 - **功能驱动**：用户实际可以使用该功能时 - **基础驱动**：所有架构层就绪且 E2E 测试通过时 - **混合方案**：每个阶段所定义的独立目标达成时 ## 决策检查清单 - [ ] 在策略选择之前存在阶段 1 的依据 - [ ] 阶段 2 产出一份完整的已选定设计，且每项设计增量都对应到当前依据、设计增量更小的方案为何不足，以及削减检验下失效的条件 - [ ] 当所列策略均无法满足全部硬性约束时，候选方案生成包含组合方案 - [ ] 每项重大风险都配有控制措施和验证点 - [ ] 每项硬性约束都对应到所选方案 - [ ] 阶段 7 的输出记录了选择结果、总体复杂度依据及设计增量；备选方案仅出现在已被接受的 ADR 中 当某个已勾选项所需的依据未知时，在该阶段停止，并明确指出继续所需的具体、可验证仓库依据要求。仅当未知项要求变更已确认的成果、目标状态需求或非目标，或需要不可逆操作授权时，才与用户交互。 ## 元认知执行指南 1. **善用已知模式**：将其作为起点，探索创造性组合 2. **依据优先级排序的调研**：依次使用仓库依据、与版本匹配的官方文档、维护良好的开源示例，最后是补充性的次要来源 3. **运用 5 个为什么**：追溯根本原因以把握本质 4. **多视角评估**：完成阶段 1-5 的依据核验与转换检验 5. **策略组合**：当单一策略无法满足全部硬性约束时，组合多种策略 6. **决策可追溯性**：将每个选择理由都映射到阶段 7 输出中的依据