architecture-exploration

架构探索

深入分析系统，提出切实可行的架构方案，并在迁移开始前帮助用户选择最佳方向。

此技能有意设定为提交前阶段。它的任务是帮助选择合适的架构，而不是执行迁移。确定方向后，将工作移交给 audit-and-migrate。

存在的意义

大型工程项目往往在编写代码之前就已失败：

1. 过早承诺 — 一个看似有前景的想法，在认真考虑其他方案之前就成了默认架构。
2. 局部推理 — Agent 优化某个子系统，却不了解整个系统的约束、所有权边界和故障模式。
3. 稻草人式比较 — 将一个偏好的方案与薄弱的替代方案比较，造成虚假的信心。
4. 迁移污染 — 在目标架构尚未真正确定之前，讨论就悄然从“我们应该构建什么？”转向“我们应该如何实现它？”

此技能旨在推动严谨探索先于实施。

严格边界

此技能不会：

• 创建迁移切片
• 创建用于执行的棘轮预算
• 开始重构
• 编写脚手架或实现代码
• 在比较完成前，将领先方案视为默认胜出方案

此技能会：

• 梳理当前系统
• 确定决策框架
• 生成多个严肃的方案
• 根据相同约束比较这些方案
• 对这些方案进行压力测试
• 推荐一个方向
• 为 audit-and-migrate 准备交接材料

直接完成所有这些工作。不要依赖其他技能替你梳理、进行压力测试或比较架构。

如果用户已经选定方向，并希望安全地落地，请停止使用此技能，改用 audit-and-migrate。

核心原则

先挖掘现实情况，再比较方案，最后提出建议。

不要从架构偏好出发。应从实际系统、实际约束和实际问题出发。

证据规范

在推荐架构之前，必须先为这项建议建立依据。

针对相关系统，主动检查：

• 当前代码路径
• 所有权边界
• 状态和数据流
• 外部契约与集成
• 文档和运维界面
• 明显的历史信号（必要时检查近期变动、已知事故和部分完成的重构）

如果本地代码库能够解答问题，就不要仅凭用户的概述建议进行重大边界调整。

如果某项判断尚不确定，应明确标注不确定性。严谨的架构建议应当恰当地表达确定程度，而不是听起来尽可能自信。

工作流

阶段 1：确定决策框架

在探索方案之前，明确实际要做的决策。

记录：

• 目标 — 用户希望实现什么结果
• 问题 — 促使变更的痛点或故障模式
• 不变量 — 必须保持不变的事项
• 非目标 — 应排除在范围之外的事项
• 约束 — 团队、工具、性能、合规、时间、兼容性、运维或组织方面的限制
• 外部界面 — API、环境变量、队列、仪表板、CLI 入口、作业、数据契约、Webhooks、合作伙伴集成
• 决策周期 — 我们要为未来 3 个月、1 年还是 3 年进行优化？

如果用户已经有心仪的候选方案，应将其视为方案 A，而不是结论。

阶段 2：梳理当前系统

在提出替代方案之前，先了解当前系统。

针对受影响的系统，梳理：

• 主要工作流
• 当前模块边界
• 数据流
• 逻辑与状态的归属
• 外部依赖
• 运维界面
• 已知痛点
• 热点——脆弱区域、变更频繁的文件、不稳定的测试、归属不明确的内容、重复逻辑、过时文档

生成简洁的当前状态图：

## Current System
| Area | Current Owner | Inputs | Outputs | Dependencies | Pain |
|------|---------------|--------|---------|--------------|------|
| ...  | ...           | ...    | ...     | ...          | ...  |

不要因为用户“已经了解系统”就跳过这一步。严谨的方案比较有赖于各方对现状达成共识。

阶段 3：生成备选方案

生成 2-4 个严肃的架构方案。

不要编造虚假的替代方案。每个方案都必须切实可行，足以让一支优秀的团队认真考虑采用。

条件允许时，纳入：

• 方案 1：渐进式路径——以较低的改动幅度改进当前系统
• 方案 2：简化路径——积极移除概念和间接层
• 方案 3：结构性路径——引入更明确的边界或新的架构形态
• 方案 4：少做一些——如果更小范围的改动可能就能解决问题

每个方案都必须说明：

• 架构形态
• 边界变化
• 归属模型
• 数据流
• 运维模型
• 保留的内容
• 变更的内容
• 简化的部分
• 变得更复杂的部分

阶段 4：分析每个方案

对每个方案进行相同的分析。

A. 适配度

该方案对以下各项的满足程度如何：

• 目标
• 不变量
• 约束
• 外部接口义务

B. 假设

列出必须成立的假设：

## Must-Be-True Assumptions
| Assumption | Why It Matters | How to Verify | Fastest Disproof |
|------------|----------------|---------------|------------------|
| ...        | ...            | ...           | ...              |

C. 失败模式

设想该方案在一年后失败，并逆向分析原因。

## Pre-Mortem
| Failure Mode | Warning Signal | Prevention |
|--------------|----------------|------------|
| ...          | ...            | ...        |

D. 权衡

根据以下方面评估每个方案：

• 概念数量——需要理解并牢记的新概念有多少
• 边界清晰度——归属是更明确还是更模糊？
• 迁移难度——后续落地有多困难
• 清理负担——留下过时代码、文档、配置或适配器的可能性有多大
• 回滚方案——回退有多困难
• 可运维性——监控、调试、故障处理和支持负担
• 可测试性——能否对系统进行确定性验证？
• 可扩展性——未来哪些变更会变得更容易？
• 锁定效应——会产生哪些新的约束？

采用相对评级并说明理由。避免伪精确。

## Tradeoff Matrix
| Dimension | Option A | Option B | Option C |
|-----------|----------|----------|----------|
| Simplicity | Medium — ... | High — ... | Low — ... |
| Migration Difficulty | ... | ... | ... |
| Cleanup Burden | ... | ... | ... |
| Operability | ... | ... | ... |
| Testability | ... | ... | ... |
| Long-Term Flexibility | ... | ... | ... |

E. 排除条件

对每个方案，说明哪些情况会使其成为错误选择。

例如：

• 需要项目并不需要的兼容性
• 增加的运维负担超出团队承受能力
• 迁移期间产生过多清理债务
• 依赖团队无法控制的外部契约
• 引入的概念没有带来足够收益

F. 未知事项

还有哪些不确定之处？请区分：

• 架构未知事项——边界或归属尚不明确
• 运行时未知事项——负载、延迟、并发、故障行为
• 组织未知事项——团队准备情况、外部使用方、运维约束

阶段 5：提出建议

不要止步于列出方案。请给出建议。

建议必须包括：

• 推荐方案
• 胜出的原因
• 次优方案落败的原因
• 否决其他方案的原因
• 哪些变化可能改变建议
• 做出承诺前必须验证的事项

如果确实无法明确推荐，请直言并准确说明哪些不确定因素阻碍了良好决策。

阶段 6：制定验证性 Spike

在做出承诺之前，提出成本最低、价值最高的 Spike，以消除不确定性。

好的 Spike 应当：

• 范围明确
• 快速完成
• 能产生证据
• 与架构相关

例如：

• 编译期模块骨架
• 针对一个关键工作流的精简端到端实现
• 事件/队列边界验证
• 用于验证数据契约形态的模拟适配器
• 针对一个疑似瓶颈进行负载实验

对每个 Spike：

## Validation Spikes
| Spike | Question Answered | Cost | Success Signal | Failure Signal |
|-------|-------------------|------|----------------|----------------|
| ...   | ...               | ...  | ...            | ...            |

阶段 7：准备移交给 audit-and-migrate

用户选定方向后，清晰地移交决策方案。

移交部分必须包含：

• 选定的架构
• 决策依据
• 不变量
• 非目标
• 关键工作流
• 外部接口
• 已知热点
• 主要迁移风险
• 预计删除区域——可能变得多余的代码、文档、脚本、配置、环境变量、适配器
• 已运行的验证性试验
• 仍需验证的事项

本部分应便于直接启动 audit-and-migrate，无需重新讨论架构。

输出约定

对于非简单的探索任务，请在 .claude/architecture/ARCHITECTURE_OPTIONS.md 或项目对应的文档位置生成一份可用于决策的文档。

使用以下结构：

# Architecture Exploration: [System Name]

## Goal

## Problem

## Invariants

## Non-Goals

## Constraints

## External Surfaces

## Current System
| Area | Current Owner | Inputs | Outputs | Dependencies | Pain |

## Option 1: [Name]
### Architecture Shape
### Why It Might Work
### Tradeoffs
### Failure Modes
### Disqualifiers
### Cleanup / Migration Implications
### Unknowns

## Option 2: [Name]
...

## Tradeoff Matrix
| Dimension | Option 1 | Option 2 | Option 3 |

## Assumptions
| Assumption | Why It Matters | How to Verify | Fastest Disproof |

## Risk Register
| Risk | Option(s) Affected | Likelihood | Impact | Mitigation |

## Validation Spikes
| Spike | Question Answered | Cost | Success Signal | Failure Signal |

## Recommendation

## Runner-Up

## Why The Other Options Lose

## Decision Needed

## Handoff to audit-and-migrate

对于较小的请求，请在对话中直接按相同结构呈现。

推理标准

避免虚假的精确性

不要编造看似严谨、实则并不严谨的数值评分。最好给出相对评级并加以说明，而不是伪造加权总分。

重视证据，而非偏好

架构偏好并非证据。建议应基于以下因素：

• 代码库结构
• 已观察到的约束
• 运营接口
• 迁移负担
• 清理负担
• 故障模式

始终包含一个更简单的选项

如果每个选项都会增加概念复杂度，很可能是你忽略了更好的路径。

不要默认重写

全面重写或大幅重置结构必须证明其合理性。这通常不是默认的最佳选择。

对称地权衡利弊

每个选项都要接受同等审视。不要仅仅因为用户偏好的选项听起来优雅，就对它放松压力测试。

何时停止

满足以下条件时，探索即可结束：

• 已清晰梳理当前系统，足以比较备选方案
• 选项中至少包含两个值得认真考虑的方案
• 每个方案都明确列出权衡和故障模式
• 建议有证据支撑
• 下一步明确：运行验证性试验或启动 audit-and-migrate

达到上述条件后，应停止探索并给出决策建议。

与 audit-and-migrate 的关系

使用此技能回答以下问题：

• “我们应该选择哪种架构？”
• “有哪些选项？”
• “这里最好的设计权衡是什么？”

当问题变为以下内容时，使用 audit-and-migrate：

• “我们决定采用选项 B”
• “现在规划迁移”
• “现在安全地落地这个方案”