module-dependency-analyzer

name	module-dependency-analyzer
description	执行模块依赖关系分析，梳理各模块之间的数据依赖、调用依赖、时序依赖和共享资源依赖， 产出依赖列表、Mermaid 依赖图、依赖矩阵、实现分层与不确定项标注。 当你需要进行"模块依赖分析"、了解"模块间关系"、生成"依赖矩阵"、 绘制"dependency graph"、或评估模块间耦合度时，使用此 Skill。

模块依赖关系分析器

核心原则

• 系统性：逐对扫描所有模块，不遗漏任何潜在依赖关系。
• 多维视角：同时提供列表、有向图、矩阵三种视图，适应不同分析场景。
• 可追溯：每条依赖必须标注推断依据（文档引用或推断理由），确保可复查。
• 风险前置：主动识别循环依赖、关键路径瓶颈和不确定项，提前暴露风险。
• 中文输出：所有输出文本使用中文，代码与专有名词除外。

输入要求

执行前，按优先级读取以下文档：

1. docs/功能设计/功能模块全拆解.md — 必须存在，是分析的主数据源。若不存在，上报 ERROR，说明缺失上游产物。
2. 项目结构设计文档 — 高优先级。通常命名为 xxx-项目结构.md，描述技术架构、分层、数据流。若不存在，基于原始设计文档和通用架构原则推断，并在输出中标注更多不确定项。
3. 原始设计文档 — 中优先级。docs/ 目录下的需求/架构/功能规格文档。

执行流程

步骤 1：读取并索引所有模块

1. 读取 功能模块全拆解.md，提取所有模块条目。
2. 为每个模块建立索引卡片，包含：模块编号、模块名称、模块类型、核心功能、颗粒度描述、所属功能域。
3. 同时读取项目结构设计文档和原始设计文档，理解系统的数据流、分层架构、外部依赖。

步骤 2：定义依赖关系类型

分析过程中，识别以下四类依赖：

依赖类型	符号	含义
数据依赖	⬅	模块 A 的运行需要模块 B 产生的数据/状态。例如：订单结算依赖商品定价数据。
调用依赖	↗	模块 A 直接调用模块 B 的接口、服务或功能。例如：支付模块调用风控模块的验证接口。
时序依赖	⏱	模块 A 的部署或初始化必须在模块 B 完成后才能进行。例如：数据库迁移必须在数据访问模块之前。
共享资源依赖	🔗	两个模块共享同一个数据库表、缓存、配置、第三方服务或消息队列。不产生单向依赖，但修改一方会影响另一方。

依赖强度分级：

• 强：缺少被依赖方，依赖方完全无法工作（阻塞性）。
• 中：缺少被依赖方，依赖方核心功能受损但可降级运行。
• 弱：缺少被依赖方，依赖方仅部分辅助功能受影响。

步骤 3：逐对推断依赖关系

采用两遍扫描策略：

第一遍 — 显式依赖提取：

• 从设计文档中直接提取已声明的依赖关系（如"用户模块为订单模块提供用户身份信息"）。
• 从项目结构设计文档中提取架构层面的依赖（如分层架构中上层依赖下层、服务间调用关系）。

第二遍 — 隐式依赖推断：

• 基于模块的核心功能和颗粒度描述，推断逻辑上的依赖关系。
• 自问："模块 A 要实现其核心功能，是否需要模块 B 已经就绪？"
• 自问："如果模块 B 不存在，模块 A 能否独立完成其职责？"

推断依据记录：每条推断出的依赖都必须记录推断依据，引用源文档的章节。格式：[文档名] §[章节] 或 基于模块描述推断 — [具体理由]。

步骤 4：构建 Mermaid 依赖图

为每个功能域绘制 Mermaid 有向图，并在最后绘制一张全系统汇总图。

Mermaid 语法规范：

• 使用 graph TD 或 graph LR，根据模块数量选择布局方向。
• 用不同线型区分依赖类型：实线（数据依赖）、虚线（调用依赖）、粗线（时序依赖）、点线（共享资源依赖）。
• 用 🔴 标注循环依赖节点。
• 当模块数量 >20 时，按功能域拆分为多张子图。

域内图：仅显示该功能域内的模块，以及它们直接依赖的外部模块（用虚线框标注外部模块所属域）。边标签使用依赖类型符号（⬅/↗/⏱/🔗）。

全系统汇总图：使用粗粒度，每个功能域作为一个节点，仅显示域间依赖。若域内循环依赖严重，用 🔴 标注该域。

步骤 5：构建依赖矩阵

构建 N×N 矩阵（N 为模块总数），行代表依赖方，列代表被依赖方：

| 模块 | M1 | M2 | M3 | ... |
|:---|:---:|:---:|:---:|:---:|
| M1 | — | ⬅强 | | ... |
| M2 | ↗中 | — | ⏱强 | ... |
| M3 | | | — | ... |

矩阵规则：

• 行 = 依赖方，列 = 被依赖方。
• 单元格内容格式：[符号][强度]（例如 ⬅强）。
• 对角线留空或用 — 表示。
• 若模块数 >30，按功能域拆分为多个子矩阵，并在最后附一个"功能域间依赖矩阵"（粗粒度，格式：[数量][类型符号]）。

步骤 6：识别循环依赖、关键路径与实现分层

循环依赖检测：

• 在依赖有向图上执行完整的图遍历，检测所有循环。
• 发现 A → B → C → A 的循环后，将其标记为 🔴 循环依赖，并在报告中突出警示。
• 对每个循环依赖提出打破建议（如引入抽象层、拆分共享数据、事件驱动解耦等）。

实现分层：

• 基于依赖图的拓扑排序，将模块划分为实现层次。
• L1（基础层） = 入度为 0 的模块（无被依赖方）。
• L(n+1) = 移除 L1..Ln 后，新产生的入度为 0 的模块。
• 重复直到所有模块都被分配层级。
• 若因循环依赖无法分层，先打破循环（附建议方案），再分层。

分层表中标注：

• 每层的模块列表、模块类型分布、可并行度（该层模块数）。
• 🔴 核心模块是否处于关键路径节点。
• 关键路径 = 从 L1 到最高层的最长路径（按模块数）。若存在多条等长路径，全部列出。

并行开发建议：

• 哪些模块组可以安全地并行开发？
• 哪些模块需要先完成接口契约定义，才能并行？
• 是否有模块可以预先开发 mock/stub，解除对其他模块的等待？

步骤 7：编写输出文档

将以上所有内容整合为一份 Markdown 文档，输出到 docs/功能设计/模块依赖关系分析.md。

文档结构严格遵循 references/output-template.md，包含以下章节：

1. 依赖关系总览 — 统计数据（模块总数、依赖总数、各确定性计数、循环依赖数、平均出入度）与 3-5 条关键发现摘要。
2. 依赖列表（按功能域分组） — 每条依赖标注：依赖方、被依赖方、类型、强度、推断依据、确定性（✅ 确定 / ⚠️ 推断 / ❓ 不确定）。
3. Mermaid 依赖图 — 域内图 + 全系统汇总图。
4. 依赖矩阵 — 全量矩阵 +（可选）功能域间粗粒度矩阵。
5. 实现分层与并行建议 — 分层表、关键路径分析、并行开发策略。
6. 循环依赖与解耦建议 — 循环依赖列表 + 每条循环的详细解耦方案。
7. 不确定项汇总 — 所有 ⚠️ 推断 和 ❓ 不确定 项，按严重程度排序（❓ 优先于 ⚠️），每项附带具体的、可操作的确认问题。

文档中附"依赖类型图例"和"推断方法论说明"作为附录。

交付前自检

• 每个模块的编号和名称与 功能模块全拆解.md 完全一致，无新增、遗漏或重命名。
• 每条依赖关系都有明确的类型、强度和推断依据。
• 所有 ⚠️ 推断 和 ❓ 不确定 项都已在不确定项章节中列出。
• 循环依赖（如有）已被识别并附有打破建议。
• Mermaid 图语法正确，可在支持 Mermaid 的 Markdown 渲染器中正常显示。
• 依赖矩阵的行列对应关系正确，无错位。
• 实现分层遵循拓扑排序原则，无层级违反（下层模块不依赖上层模块）。
• 🔴 核心模块的关键路径标注已完成。

自检通过后，本阶段直接完成。本 Skill 无确认点，上报 DONE 即可。

约束与禁忌

• 禁止跳过模块：功能模块全拆解.md 中登记的每个模块都必须参与分析，不得遗漏。
• 禁止无依据推断：每条依赖必须有文档引用或明确的推断理由，不得凭空臆造。
• 禁止遗漏循环依赖：必须执行完整的图遍历检测，不得依赖人工目视。
• 产物路径固定：输出路径严格遵守 docs/功能设计/模块依赖关系分析.md。
• 禁止自行降级方案：方案级降级（如跳过某些功能域、简化依赖类型）必须上报 ERROR 等待人工介入，不得自主执行。

参考文件

文件	归属	用途	加载时机
.claude/workflows/project-design-pipeline/references/directory-convention.md	工作流共享	全局目录结构约定、路径格式硬性约束	前置读入
references/output-template.md	Skill 独有	输出文档的精确结构与各节填写规范	步骤 7
docs/功能设计/功能模块全拆解.md	上游产物	模块登记表（主数据源）	步骤 1

共享资源位于消费者项目的 .claude/workflows/project-design-pipeline/references/ 目录下。