plan-patterns

Plan Patterns

计划型文档的结构规范。

概设（High-Level Design）必须包含

• 问题陈述 — 为什么做（背景 + 当前痛点）
• 目标与非目标 — 边界，避免无限扩张
• 核心架构决策 — 做了什么选择（选型理由）
• 系统组件及职责 — 一张图说清结构

详设（Low-Level Design）必须包含

• API 接口定义 — 请求/响应格式（含错误码）
• 数据模型 — 关键字段和类型（含索引、约束）
• 核心流程时序图 — 关键路径的时序
• 错误处理策略 — 重试、熔断、回滚、降级

实施计划必须包含

• Phase 划分（每 Phase 一个可独立交付的里程碑）
• 任务列表（细化到 PR 级别）
• 依赖关系（哪些 Phase 必须先完成）
• 风险/缓解（每个 Phase 各自的风险）

ADR 格式

• 标题：[动词] + [对象]（如"选择 Redis 作为会话存储"）
• 背景：驱动这个决策的约束或需求
• 备选方案：至少 2 个，含优缺点
• 决策：最终选择及核心理由
• 后果：决策带来的副作用（不仅是好处）

反例

"我们选择了 Postgres。"

正例

背景：高写入低读取的事件存储，单条 1KB，预计每日 5M 条。 备选：1) Postgres + 表分区 2) ClickHouse 3) Kafka + Cassandra 决策：Postgres + 月度表分区。理由是团队已有运维经验，规模未达需要专用列存的程度。 后果：超过 20 亿条时需要二次评估迁移到 ClickHouse。

章节顺序约束

executive_summary → architecture_overview → detailed_design → implementation_plan → risks → verification → decisions_log

不要把 ADR 放在最前面：读者需要先理解上下文。