| name | flow-design |
| description | 技术设计师。把 REQUIREMENT.md 转化为可执行的技术设计 DESIGN.md，含技术栈预选（5~6 卡让用户选）、既有架构对齐（brownfield）、技术决策清单（备选+理由+代价）、数据流/架构图、ADR、风险分析和架构沉淀建议。优先使用 GitNexus MCP 定位既有模块和抽象，grep 作为回退。Use when 用户确认 REQUIREMENT.md 后需要进入技术设计阶段，或需要技术选型/架构评审时。 |
flow-design — 技术设计
Goal
把需求转化为可执行的技术设计，确保 brownfield 项目沿用既有架构，每个决策都有理由和代价。
Workflow
0- 架构级变更预检（二次保险）
如果 CHANGE.md 末尾已有「架构层影响声明」或「走 A-architect 后回来」标记 → 跳过。
否则按 0-change 步骤 0.4.1 标准重新判定：
- 命中 + ARCHITECTURE.md 存在 → 检查 ADR 冲突，提示在 §1 显式声明 supersede 关系
- 命中 + ARCHITECTURE.md 不存在 → 反问用户：先跑 flow-architect / 继续但强制加 ADR 声明 / 重判
- 未命中 → 直接进步骤 0
GitNexus 路径（优先）：调用 gitnexus_impact({target: "ADR 涉及的关键符号", direction: "upstream"}) 检查影响范围，确认是否会与现有 ADR 冲突。
0. 技术栈预选（独立一条消息，等用户选定）
例外（可跳过）：
- CONTEXT.md 已有「已锁技术决策」→ 直接读用
- 用户描述含强偏好 → 锁定后跳过
- 纯库/SDK/CLI → 只选语言
常规路径：
加载 references/tech-stacks-excerpt.md，按「适用矩阵」过滤出 5~6 张最匹配卡片：
- 5~6 张卡片（编号 + 名称 + 一句话栈描述）
- 必给 1 首选 + 1 备选，理由结合 REQUIREMENT.md 的 AC + 非功能需求
- 显式排除 1~2 个 + 理由
- 末尾：
请回复数字（如 "1"）或描述偏好，选定后我才出具体 ADR 与架构图。
选定后：写入 DESIGN.md「## 0. 技术栈选定」段，后续所有设计基于这个栈展开。
0.5 既有架构对齐（brownfield 必跑）
触发：CONTEXT.md 存在且非空。新创项目跳过。
0.5.1 列出本次 change 会触碰的既有模块
GitNexus 路径（优先）：
- 调用
gitnexus_query(query="<REQUIREMENT 关键概念>", goal="find affected modules", task_context="<change描述>") → 返回 affected processes 和 process_symbols
- 调用
gitnexus_cypher 查询涉及的 Community/模块：
MATCH (c:Community) WHERE c.keywords CONTAINS "<关键词>" RETURN c.heuristicLabel, c.symbolCount
- 从返回结果直接提取：触碰模块（既有 · 来自 GitNexus） / 新增模块 / 禁动清单
grep 回退：基于 REQUIREMENT.md 和 CONTEXT.md，grep 出实际会涉及的模块：
- 触碰模块（既有 · 来自 grep）
- 新增模块
- 禁动清单（与本次无关，AI 不许"顺手"碰）
0.5.2 对齐既有抽象（防重复实现）
针对本次 change 需要的能力，先问已有的能不能用。禁止"顺便引入 X 库"——必须写出为什么不用既有的才能引新。
0.5.3 沿用模式 vs 引入新模式
显式声明每个关键决策的选择。引入新模式必须有充分理由。
0.5.4 写入 DESIGN.md
把上面三段写入 DESIGN.md「## 0.5 既有架构对齐」段。
1. 技术决策（每条都要有理由）
格式：决策 → 备选 → 选择理由 → 取舍代价
2. 数据流 / 架构图
使用 ASCII 框图或 Mermaid。说明数据/事件流向、关键状态机、边界。
3. ADR
凡是「以后可能被推翻」的决策，单独写一份 ADR 到 .specs/adr/<NNN>-<title>.md。
4. 风险
至少列 3 条：实现风险 / 上线风险 / 长期债务。每条给缓解方案。
5. 不在范围内
显式列出这次设计不解决但未来需要的问题。
9. 架构沉淀建议（软约束 · 为 flow-evolve 准备素材）
本 change 如果引入了"项目级有复用价值"的东西，记在这里。以后 flow-evolve 会扫这段批量同步到 CONTEXT.md。
入选阈值（任一）：
- 新增可复用抽象（以后别的场景也用得到）
- 项目级技术决策（"以后都这么干"的取舍）
- 跨模块契约（新增/修改公共 API/Schema/事件总线）
- 依赖变动（新增/升级/替换核心包）
- 禁动清单变动
没有就整段写「本 change 无架构层面沉淀建议」，不要凑数。
Constraints
- R3.1：禁止给具体代码实现（伪代码可，函数签名可，完整函数体不可）
- 每条决策必须给理由 + 取舍
- 不允许"使用最佳实践"这类无意义短语
Validation
Resources
references/DESIGN.md — 产出模板references/tech-stacks-excerpt.md — 技术栈卡片节选（适用矩阵 + 模板）
