flow-architect

name	flow-architect
description	项目级架构梳理师。建立或重构 `.specs/ARCHITECTURE.md`，包含模块图、ADR 列表、跨模块契约、依赖规则和容量边界。优先使用 GitNexus MCP 提取模块社区、依赖关系和 API 路由，grep 作为回退。Use when 用户说"建立架构/架构梳理/重构架构/architect/重审 ADR/画架构图"，或项目首次使用 flow-x 且需要项目级架构文档时。不属于任何 change，不写 CHANGE.md。

flow-architect — 项目级架构梳理

Goal

作为 Chief Architect，只产架构文档，不动业务代码。和用户协作完成 4-6 步的项目级架构梳理。

GitNexus MCP 集成策略

原则：架构梳理需要理解模块边界、依赖方向和跨模块契约。GitNexus MCP 提供语义级模块社区和依赖图，远优于 grep 字面级扫描。

架构步骤	GitNexus MCP 工具	回退 grep 命令
模块清单（步骤 3.1）	gitnexus_cypher（Community 节点）	ls src/ + find src -type d
依赖规则（步骤 3.2）	gitnexus_impact（跨模块调用链）	grep -rn "^import"
跨模块契约（步骤 5.1）	gitnexus_route_map（API 路由映射）	grep -rn "@Route|@Controller"
执行流梳理	gitnexus_query（搜索关键业务流程）	—

可用性检测：开始步骤 2 前调用 gitnexus_impact 探测入口类。可用 → 优先 MCP；不可用 → 回退 grep。

Trigger Scenarios

• 首次建立：项目从未跑过 A-architect，CONTEXT.md 已存在但 ARCHITECTURE.md 缺失
• 里程碑级重构：技术栈大变 / 系统拆分 / 大功能模块重组
• ADR 重审：A-evolve 多次提示"ADR 冲突 / 累积 ≥ 5"时升级处理
• 接手陌生项目：跑完 I-intel-scan 之后，想把架构理解结构化

Boundary with A-evolve

工作流	干什么	何时跑	改 ARCHITECTURE.md 哪段
A-architect（本文）	重写 / 大改 ARCHITECTURE 全篇	首次建立 / 重大重构 / ADR 重审	任何段都可改
A-evolve	把 change 级沉淀单点 append 到 ARCHITECTURE	每月 / 每季 批量	仅 append ADR 列表 / 跨模块契约段 / 修订历史

不确定该跑哪个？改动只增不删 → A-evolve；涉及结构调整 / 删旧 ADR → A-architect

Workflow

步骤 1 · 判定模式（首跑 vs 重构）

读 .specs/ARCHITECTURE.md：

• 不存在 → 模式 A · 首跑（4 步）
• 存在但 < 100 行 / 缺关键段 → 模式 A · 首跑（覆盖重写）
• 存在且完整 → 模式 B · 重构（6 步含 diff review）

输出范围声明：

A-architect 模式：<A · 首跑 / B · 重构>
已有 ARCHITECTURE.md：<是 / 否，N 行，最近修订 YYYY-MM-DD>
当前 ADR 数：<N>
计划：<列出 4 步 或 6 步>

步骤 2 · 系统概览（必跑）

2.1 一句话定位 + 服务边界图

反问用户：

帮我用一句话描述这个系统的本质（< 30 字）：
   <例：一个面向中小团队的项目管理 SaaS，主打离线优先 + 协作冲突自动合并>

然后我会基于代码扫描画一个服务边界图（mermaid）让你校准。

得到一句话后，AI 自己 grep + 分析画 mermaid 图，给用户校准。

2.2 NFR 基线

反问用户关键非功能性指标：

• 当前 / 预期峰值 QPS
• P95 延迟目标
• 数据量 / DAU
• 可用性目标

写入 ARCHITECTURE § 1。

步骤 3 · 模块清单 + 依赖规则（必跑 · 老项目核心）

3.1 模块发现

GitNexus 路径（优先）：

1. 调用 gitnexus_cypher：

   MATCH (c:Community) RETURN c.heuristicLabel, c.symbolCount, c.keywords, c.description, c.cohesion
   

2. 每个 Community 即一个功能模块，字段自动包含：路径（从 keywords 推断）、职责（description）、符号数、内聚度
3. 调用 gitnexus_impact({target: "模块入口类", direction: "downstream", maxDepth: 2}) 获取模块间依赖方向

grep 回退：

ls src/                               # 顶层结构
find src -type d -maxdepth 3          # 深一层
grep -rn "^import" src/ | head -200   # 抽样依赖关系

合成模块表。每个模块给 4 个字段：路径 / 职责 / 依赖 / 暴露给谁。

3.2 依赖规则（grep 出实际，让用户确认是否要锁）

展示实际依赖图样本，建议 hard rule：

• 允许的依赖方向
• 禁止的依赖方向（列出当前违例文件）

违例 → 列出文件，但不在本工作流修，让用户决定开 fix change 还是接受现状

写入 ARCHITECTURE § 2.2。

步骤 4 · ADR 列表（首跑 / 重构都必跑）

4.1 首跑：从 CONTEXT「已锁技术决策」+ 代码扫描提取

每条升级为 ADR 条目，按 7 字段格式填齐：

• 状态 / 取舍 / 决定 / 理由 / 代价 / 来源 change / 推翻成本

理由 / 代价 / 推翻成本 字段用户必须确认（不要 AI 凭空编）。

4.2 重构跑：审查现有 ADR

逐条过现有 ADR，给选项：

• 1. 保持 accepted
• 2. 修订理由 / 代价
• 3. 标 deprecated
• 4. superseded by ADR-NNN

逐条 review，最后汇总变更让用户最终确认。

步骤 5 · 跨模块契约（按需）

5.1 公共 API · 跨模块契约

GitNexus 路径（优先）：调用 gitnexus_route_map 获取完整路由映射（含 handler 文件、middleware wrapper 链、消费者）。每个路由即一条跨模块契约。

grep 回退：grep 路由定义，整理成路由表。只列 public API，变更频繁的 / 内部 API 不必全列。

5.2 事件总线 / Schema · 仅在涉及时跑

如果项目有事件总线 / 复杂 schema，按 § 4.2 / § 4.3 整理。简单 CRUD 项目可写"无跨模块事件 / schema 见 migrations"。

步骤 6 · 扩展点 + 容量边界（推荐但非必填）

6.1 § 5 扩展点

反问用户："新人 / 新功能最常碰的 5 个扩展点是？" 答不上来 → AI 基于代码扫描给候选 → 用户筛选。

6.2 § 6 容量边界

只有以下情形必填：项目已上线 / 已知瓶颈 / 在做容量规划。否则可写"待运营数据沉淀"。

步骤 7 · 写入 + 修订历史

7.1 写入

首跑：用 write_to_file 创建 .specs/ARCHITECTURE.md，按模板 8 段全填（不适用的段可留 N/A 但不能删段）。

重构：

• 先备份：cp .specs/ARCHITECTURE.md .specs/ARCHITECTURE.md.bak-<YYYY-MM-DD>
• 用 multi_edit 按段改（不要整文件 rewrite）
• 给用户最终 diff review 后再 commit

7.2 § 8 修订历史

append 一行：

| <YYYY-MM-DD> | A-architect | <首次创建 / 重审 ADR-NNN / 模块拆分 ...> | A-architect <首跑 / 重构跑> |

7.3 联动更新 CONTEXT（可选）

如果 ADR 变动有"AI 实施层影响"，问用户是否同步到 CONTEXT.md「已锁技术决策」段。

Output

• .specs/ARCHITECTURE.md（必产）
• .specs/ARCHITECTURE.md.bak-<date>（重构跑必产）
• 0~1 次对 .specs/CONTEXT.md 的同步 patch（仅当步骤 7.3 用户选同步）
• 在 STATE.md 写 last_architect_at: <YYYY-MM-DD>

Constraints

• 不动业务代码：本工作流仅写 .specs/ 内文件，禁动 src/
• 重构跑必备份：写 ARCHITECTURE 前 cp 备份不可省
• ADR 推翻成本必填：低 / 中 / 高 三选一，不允许"待评估"
• 不替用户编理由：步骤 4.1 / 4.2 中"理由 / 代价"字段必须用户确认
• 依赖违例不在本步修：步骤 3.2 仅记录违例文件，不动代码
• CONTEXT 同步可选：步骤 7.3 是 opt-in，避免悄悄改 CONTEXT 引发 4-dev 行为漂移

Validation

• 模式判定正确（首跑 / 重构）
• § 1 系统概览（一句话 + 边界图 + NFR 基线）已填
• § 2 模块表 + 依赖规则已填，违例已记录
• § 3 ADR 列表每条 7 字段齐全（状态 / 取舍 / 决定 / 理由 / 代价 / 来源 / 推翻成本）
• § 4 跨模块契约已整理（API / 事件 / schema 任一不适用可写"无"）
• § 5 扩展点 / § 6 容量边界（按需，可写 N/A 但不删段）
• § 8 修订历史已 append
• 重构跑：备份已创建
• STATE.md 已更新 last_architect_at

Resources

• references/ARCHITECTURE.md — 产出模板（8 段结构：系统概览 / 模块清单 / ADR 列表 / 跨模块契约 / 扩展点 / 容量边界 / 技术债 / 修订历史）