flow-design

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 路径（优先）：

1. 调用 gitnexus_query(query="<REQUIREMENT 关键概念>", goal="find affected modules", task_context="<change描述>") → 返回 affected processes 和 process_symbols
2. 调用 gitnexus_cypher 查询涉及的 Community/模块：

   MATCH (c:Community) WHERE c.keywords CONTAINS "<关键词>" RETURN c.heuristicLabel, c.symbolCount
   

3. 从返回结果直接提取：触碰模块（既有 · 来自 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

• 技术栈已锁定（## 0 段填齐）
• 既有架构对齐已写入（brownfield 必跑 · ## 0.5 段齐全）
• 每条决策都有「备选 + 理由 + 代价」
• 至少一张数据流/架构图
• 风险 >= 3 条且每条有缓解
• 大的或可逆性低的决策都有对应 ADR
• 不含完整代码实现
• §9 架构沉淀建议已写（有就填表，没有就写"无建议"，禁凑数）

Resources

• references/DESIGN.md — 产出模板
• references/tech-stacks-excerpt.md — 技术栈卡片节选（适用矩阵 + 模板）