hf-to-product-architecture

hf-to-product-architecture

把「系统长什么样」钉成可继承的产品级地图，供后续特性增量架构与切片对齐。不是特性实现设计。敌人是复杂度——变更放大、认知负荷、未知的未知（Ousterhout）；判据是长期演进成本。

前置

1. 绿地：已按 product-layer-templates 落盘，且 hf-grill-with-docs 已确认 CONTEXT.md（及台账）。
2. 读 product/progress.md（若有），确认当前在产品架构阶段或尚未确认架构。
3. 加载 hf-codebase-design 词汇；领域边界不清时加载 hf-domain-modeling（可升 CONTEXT-MAP.md）。
4. 方法论细节（质量属性场景、易变性清单、适应度函数、ATAM-lite）见 references/architecture-methodology.md，按需加载。
5. 更新 product/progress.md：当前阶段 to-product-architecture。

流程

1. 架构特征（驱动力）：从 grill 结论、CONTEXT.md、台账提炼 3~5 个驱动性架构特征（可演进性、可测试性、伸缩、容错、安全……），各配一条可检验的质量属性场景（刺激→响应→度量）。拿不准记入假设台账。特征先于风格：后续每步取舍都必须能回应这些特征。
2. 原则与风格：选定架构风格（分层 / 六边形 / 整洁等）与依赖硬规则，声明它如何服务第 1 步的特征；难逆转点写 ADR。
3. 逻辑划分（按易变性）：3~7 个模块或限界上下文；每个一句话职责 + 它封住的易变性（哪个可能变化的设计决策被藏进内部）。按业务易变性切，不按纯技术层切蛋糕；只为有证据的易变性开缝。多上下文维护 CONTEXT-MAP.md。
4. 开发视图：目录/多模块划分、源码与测试放置、命名约定。须让「新代码放哪」有唯一显然答案（对抗未知的未知）。
5. 关键场景：2~5 条端到端路径，作为垂直切片判据；每条标注它验证哪个架构特征。建造模式建议第一片为行走骨架（feature.md 标 - 骨架: 是）。
6. 横切与 ADR：错误、鉴权、持久化、观测等只写约定与链接，不写字段级细节。
7. 演进与适应度：为已识别易变性写演进路径（变化真发生时改哪里、不改哪里）与量化复核触发（吞吐、延迟、模块数、团队数等信号，触发即重开本阶段）；为依赖硬规则与关键特征配适应度函数，写清校验方式与频率（CI / 评审项 / 定期）。
8. 落盘 product/architecture.md（≤120 行），确认行先留空。
9. 送审 hf-review（产品架构）→ product/reviews/product-architecture-review.md。
10. 用户确认后写入架构与评审的确认行；更新 product/progress.md → ready。

技法（按需）

• 复杂度三问：比较候选划分——一次典型变更波及几个模块（变更放大）？理解一个模块要先懂几个其他模块（认知负荷）？新会话能否不扫全库就知道代码放哪（未知的未知）？选三问总和最小的方案。
• 可逆性分类：双向门（易逆转）→ 快速给默认并记 product/assumptions.md；单向门（存储引擎、事件契约、对外 API 等）→ 放慢，按 ADR 三条件进 docs/adr/。最后责任时刻之前不锁死，但推迟的决策要用接缝隔离成局部。
• ATAM-lite：特征互相冲突（一致 vs 可用、性能 vs 简单）时写明取舍与敏感点，敏感点进 ADR，正文只链接；当前最可能让架构返工的 1~3 个风险宜早验证，常是行走骨架的内容。
• 备选设计：风格或划分存在实质分歧时，用 hf-codebase-design 的 design-it-twice 出两个对立方案，按深度/局部性/接缝位置与复杂度三问评分后定。
• 彩色/多色建模：在 grill/本阶段澄清领域角色与状态时使用，结论写入逻辑划分与 CONTEXT，不单独成阶段。
• 4+1：默认合并为逻辑 + 开发 + 场景三块；物理/过程视图仅在部署/并发成为硬约束时追加 ADR。

红线

• 无 CONTEXT 确认不得宣称产品架构已确认
• 不把特性级接口签名、字段表、票级细节写入产品架构
• 不在本阶段实现业务代码或拆完整特性票单
• 每条结构决策可追溯到某个架构特征或已识别易变性，禁止无驱动力的风格与划分
• 演进 ≠ 投机：不为未确认的未来引入抽象层与接缝；演进节只写路径与触发，不预写未来设计
• 欠定 → product/assumptions.md，不静默填补