技术方案设计

何时使用

• 用户说"写个技术方案""设计一下实现方案";
• 需求规格已确认,动手前要定架构和关键取舍;
• 方案有争议,需要文档化对比和选型依据;
• 大改动上线前,需要风险评估和回滚方案。

使用步骤

第 1 步:确认输入

• 需求规格(来自 requirement-clarifier 或 PRD);
• 现有系统现状(技术栈、模块、数据);
• 约束:时间、团队规模、运维能力、合规。

第 2 步:明确目标与不做的事

• 目标:解决什么问题、成功长什么样(可度量);
• 不做:明确排除的范围,防止方案失控。

第 3 步:方案对比与选型

每个关键决定至少列两个方案,写清楚:

选型结论要写"为什么选 A 不选 B",不要只写结论。架构问题本质是取舍,不存在的方案才是问题。

第 4 步:写架构与细节

按模板输出:

# 技术方案:<名称>

## 背景与目标
## 方案对比
## 选型结论
## 架构设计
## 数据模型
## 接口设计
## 关键流程
## 风险与应对
## 上线与回滚

原则:

• 架构画清模块和调用方向,数据流讲"请求怎么走";
• 数据模型列出核心表/字段/关系,引用 db-schema-designer;
• 接口列关键契约,引用 api-contract-designer;
• 风险每条配应对,不说"注意一下"这种空话。

第 5 步:校验与评审

用 design_checker.py 自查(见辅助脚本),修掉标出的缺口;然后把方案给相关人评审,重点确认取舍是否成立。

输入与输出

• 输入:需求规格 + 系统现状 + 约束;
• 输出:技术方案文档(含选型依据、风险、上线方案)。

示例

方案对比节选:

## 方案对比
| 方案 | 优点 | 缺点 |
|---|---|---|
| A:单体改造 | 改动小,上线快 | 长期耦合,扩展受限 |
| B:拆独立服务 | 边界清晰,独立扩展 | 需要消息队列与部署改造 |

## 选型结论
选 A:当前团队 3 人、上线窗口两周,拆分收益不足以覆盖成本;留 B 作为下一阶段演进方向。

辅助脚本

scripts/design_checker.py 检查方案文档的完整性:

python skills/tech-design-writer/scripts/design_checker.py <方案.md>

检查:必需章节是否齐全且非空、方案对比是否至少两个方案、选型是否给理由、风险是否每条有应对、有无占位符。脚本只做标记,结论需要人确认。

注意事项

• 取舍要写理由:不写理由的选型等于没选;
• 方案别堆术语,评审的人可能不熟你用的框架;
• 风险写"发生概率 × 影响 × 应对",别只列现象;
• 上线方案包含回滚:出问题怎么退,比怎么上更重要。

不适用场景

• 需求还没确认(先澄清需求);
• 只问某个技术怎么用,不需要方案文档;
• 已经进入编码阶段,需要的是任务拆解(用 task-decomposer)。

验证方式

1. 触发:"写技术方案";
2. 跑脚本:design_checker.py 无"必须"级问题;
3. 走查:每个选型都有理由,每条风险都有应对;
4. 确认:评审人对取舍无异议。