用途
Architecture Audit 用于回答一个核心问题:代码库的模块边界是靠结构本身维持,还是仅靠约定维持,且在何种程度上与其规模相匹配。它依据《模块化应用架构标准》对应用代码库进行循序渐进的模块化审计,每个步骤使用特定参考文件并产出供最终报告使用的工件。
主要能力
- 模块映射:识别任意技术栈中的物理与逻辑模块,并将每个模块归入一种角色:组合根、契约、功能、共享领域、共享通用、全局服务或基础。
- 依赖图分析:提取导入边并映射到模块,发现禁止的依赖边、循环、深层导入以及扇入/扇出热点。
- 组装分析:检查实现选择、组合根、路由组装、功能间导航、分层与包含关系,区分集中式组装与分散组装及隐藏的导航耦合。
- 管控分析:区分仅写于文档的规则与由工具强制执行的规则,检查遗留违规跟踪方式及本地检查。
- 架构评分:按有效画像应用四维评分规则,映射成熟度等级,判定规则与反模式,并按固定顺序给出整改计划。
- 报告生成与校验:生成固定 10 个章节的 Markdown 报告和 JSON 导出,并校验结构与格式。
使用方式
技能以规则序列执行,共 7 条规则:模块映射、依赖图、组装分析、管控分析、架构评分、报告生成、格式强制。步骤 1 检测技术栈与工作区,用固定脚本清点源文件,分类模块角色并记录驱动因素,写入 data/files.tsv、data/inventory.json 和 data/module_map.tsv。步骤 2 用固定指标脚本提取导入边,计算画像、耦合、违规、循环、深层导入、规模与变更局部性,保存 data/metrics.json。步骤 3 保存组装分析工件,步骤 4 保存管控分析工件。步骤 5 必须在写任何报告前确定每项检查结果、四维得分与总分。步骤 6 依据 assets/report-template.md 合成报告,步骤 7 校验后导出到 ./reports/<YYYY-MM-DD>-<project>-architecture-audit.md。
也可通过 CLI 命令 step by step 执行,或在会话中由编排器分波调度子代理:第 1 波 graph-analyzer,第 2 波 composition-analyzer,第 3 波 control-analyzer,第 4 波 report-writer。两种路径产出相同报告。操作员可指定画像(例如按 Large 审计),步骤 1 记录原因,步骤 2 传给脚本,报告同时显示测量画像与实际有效画像。
评分与成熟度
四个维度各 25 分:结构(S1 边界形式适配画像 8、S2 功能规模均衡 6、S3 文件规模 5、S4 下层角色向下依赖 6)、集成(I1 功能隔离 7、I2 无环图 6、I3 公共表面 4、I4 导航契约 4、I5 分层与包含 4)、组装(C1 可替换接线 8、C2 根仅持有组合 7、C3 路由组装 5、C4 根与画像相称 5)、管控(K1 书面标准 5、K2 机械执行 10、K3 债务棘轮 5、K4 本地反馈 5)。总分 = round(100 × 得分 ÷ 可能分),半数向上取整。当没有任何必需规则类被强制执行时(K2 得 0),总分上限 64;仅部分执行或尚无必需类时上限 84。成熟度等级:0–39 Monolithic,40–64 Partially modular,65–84 Modular,85–100 Governed modular。
适用场景
适合对应用代码库进行只读架构健康检查,尤其关注模块边界、依赖方向、功能隔离、组合根与规则执行力的团队;也适合需要跨项目、跨运行可比较审计结果的场景,因为图指标由固定脚本计算。
限制
审计绝不修改、创建或重新格式化被审计仓库中的任何文件(reports/ 除外),不运行项目自身的 linter、测试或构建。模块角色不能仅凭目录名判定。规则被写入文档不等于被执行,执行意味着违规会导致 CI 失败或必须的钩子失败。不假设信息:找不到或无法测量时报告「Not found」或「Not measured」。上传到 Google Drive 仅在用户明确要求时执行。