analyze-repo

仓库分析

生成一份独立的 HTML 审计报告，清晰呈现仓库架构、依赖压力和影响最大的技术债。每项结论都必须能追溯到测量结果或明确列出的文件；不确定之处须明确标注。

工作流

1. 建立证据台账

在选择命令前，先检查仓库指南和环境。从源代码指标中排除生成文件、供应商代码、缓存和依赖目录。 收集以下信息：

• 仓库概况：源文件、语言、顶层模块、入口点
• 组织结构：功能／层／包的归属情况，以及目录布局是否符合运行时和领域模型
• 组合方式：模块如何协作、接口和接缝位于何处，以及复杂性是集中存在还是在多个调用方中重复
• 架构：运行时边界、数据流、持久化、外部系统
• 依赖：高扇入模块、依赖方向、接缝违规，以及工具可验证时的循环依赖
• 模式：已确立的前端、后端、集成、状态、持久化和设计模式；相互竞争的实现及未完成的迁移
• 热点：大型或复杂文件、职责混杂、TODO/FIXME 聚集情况
• 决策：现有 ADR，以及仓库文档中缺少理由说明的重要决策
• 验证：测试位置、测试运行器配置、覆盖率产物和 CI 检查

使用确定性命令或项目工具统计数量并验证依赖图相关结论。记录包含以下字段的证据台账：

字段	要求
结论	一项可证伪的陈述
证据	命令输出、配置或准确的文件／模块路径
方法	证据的收集方式
置信度	verified、supported 或 unverified

只有在覆盖率产物或已执行的覆盖率命令提供数值时，才能报告测得的覆盖率。否则，报告测试信号，并将覆盖率标记为 Not measured。

当架构决策具有重要影响时，加载 references/architecture-decisions.md。在称某项决策缺少文档说明前，先搜索现有 ADR 和设计文档。将观察到的选择与推断出的理由分别记录；缺失的业务约束应作为问题提出，而不是作为发现结论。

在有帮助时，通过可用的子 Agent 机制委派广泛的仓库探索。向探索者提供台账格式，并要求每个非空类别都列出具体路径。父 Agent 负责核验返回的结论。

完成条件：每项候选发现都有证据和置信度标签。

2. 综合发现

加载 codebase-design 技能，并始终使用其中的术语。通过模块的接口、实现、接缝、适配器、深度、杠杆效应和局部性来评估模块。仅将 边界 用于领域或部署边界；将 接缝 用于行为可以变化的位置。

将已核实的证据归入 architecture、organization、composition、dependencies、patterns、hotspots、decisions 和 verification。在将差异视为不一致之前，先识别已确立的前端／后端模式。合并根因相同的重复症状。按以下顺序排列发现：

1. 生产或安全风险
2. 变更放大效应和缺陷风险
3. 开发者阻力和上手成本
4. 低紧急度的清理工作

每项发现都必须指出受影响的范围、说明其影响，并建议一项范围明确的后续行动。将观察到的事实与解读区分开。对疑似直通模块应用删除测试；只有在多个适配器或其他已证实的差异能够佐证时，才将接缝视为真实存在。

对于影响重大的未记录决策，添加一个 ADR 候选项，而不是臆造理由。将已记录的决策链接到对应的现有 ADR。将尚未解决的候选项交给 architect 技能，由其比较选项并提出决策建议；只有在该决策确定且用户要求提供持久记录时，才起草 ADR。

完成标准：最重要的发现有证据支持，使用共享词汇，区分已确立的模式与意外差异，并按影响排序。

3. 选择可视化方式

每份报告都需要架构可视化，但不要求使用特定渲染器。选择能够清晰传达证据的最精简格式：

• **内联 SVG：**适用于精心设计的架构图、数据流图或热点图。加载 references/svg-patterns.md。
• **可缩放图表：**当标签或边在报告宽度下无法保持清晰可读时使用。加载 references/diagram-shell.md；其外壳可接收内联 SVG，包括由图形工具预先渲染的 SVG。
• **HTML/CSS 结构：**适用于无需自由边线的简单分层结构或小型关系图。

必须对生成的报告文本进行 HTML 转义。必须对 SVG 文本和属性进行 XML 转义。如果使用图形渲染器，先对标签进行该渲染器所需的编码，再进行渲染，并嵌入生成的 SVG，而不是仓库控制的标记。

完成标准：所选可视化能展示仓库中真实存在的边界，且每个突出显示的问题都对应一项发现。

4. 生成报告

编写前，先阅读以下参考资料：

1. references/report-design-system.md
2. references/report-components.md
3. references/html-report-template.md
4. 如存在 ADR 或 ADR 候选项，则阅读 references/architecture-decisions.md
5. 第 3 步中选定的可视化参考资料

指定一次路径，并在之后重复使用：

REPORT_PATH="${TMPDIR:-/tmp}/repo-analysis-$(date +%Y%m%d-%H%M%S).html"

报告必须包含：

1. 仓库身份、分析日期、范围和一句话评估
2. 附带来源信息并明确标出未知项的测量摘要
3. 架构可视化及说明性标题
4. 使用共享词汇进行的模块设计评估
5. 排名后的发现，包含严重程度、置信度、证据、影响和后续行动
6. 决策记录，链接现有 ADR 并列出符合条件的 ADR 候选项
7. 聚焦证据的热点／文件概览，而非穷举文件列表
8. 按优先级排列的建议和验证清单

完成标准：文件存在、不含未解决的模板变量，并且报告中的每项发现都有对应的台账条目。

5. 检查渲染效果并交付

尽可能通过可用的浏览器自动化打开报告；否则使用平台打开器（open、xdg-open 或 start）。检查页面在桌面端和窄屏宽度下的渲染效果。确认：

• 核心内容不依赖脚本、样式、字体或网络资源才能正常显示
• 架构标签、连线、图例和说明文字清晰易读
• 表格／卡片没有溢出，也不会遮挡证据
• 交互控件的键盘焦点清晰可见
• 浅色和深色配色方案均保持足够的对比度
• 如有缩放控件，说明文字在视口裁切范围之外仍可见；且在最大缩放和各个平移极限下均能正常工作

修复问题并重复检查。交付报告路径，并按置信度概述最重要的 3–5 项发现。提出后续的架构质询环节；仅在用户选择参加后才开始。

完成门槛

只有满足以下条件，分析才算完成：

• 每项报告结论都有证据和置信度标签
• 使用共享代码库术语检查了组织结构、代码组成以及既有前端／后端模式
• 重要决策关联到现有 ADR、标注为 ADR 候选，或说明为何不需要决策记录
• 已测量覆盖率和复杂度，或明确标注为未测量
• 报告包含适合相应渲染器的架构可视化
• 对仓库控制的文本进行编码，以适配其输出上下文
• 渲染后的报告通过桌面端、窄屏和图表检查
• 按影响程度对最重要的 3–5 项发现排序，并告知用户

参考资料路由表

优先级	加载时机	参考资料
1 — 必需	生成任何报告时	references/report-design-system.md
1 — 必需	构建报告章节时	references/report-components.md
1 — 必需	组装最终 HTML 时	references/html-report-template.md
2 — 有条件	存在现有 ADR 或重要但未记录的决策时	references/architecture-decisions.md
2 — 有条件	渲染经过整理的内嵌 SVG 时	references/svg-patterns.md
2 — 有条件	图表需要缩放或平移时	references/diagram-shell.md