| 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 路径（优先）：
- 调用
gitnexus_cypher：
MATCH (c:Community) RETURN c.heuristicLabel, c.symbolCount, c.keywords, c.description, c.cohesion
- 每个 Community 即一个功能模块，字段自动包含：路径（从 keywords 推断）、职责（description）、符号数、内聚度
- 调用
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，给选项：
-
- 保持 accepted
-
- 修订理由 / 代价
-
- 标 deprecated
-
- 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
Resources
references/ARCHITECTURE.md — 产出模板（8 段结构：系统概览 / 模块清单 / ADR 列表 / 跨模块契约 / 扩展点 / 容量边界 / 技术债 / 修订历史）
