文章总结： repo-analyzer是基于ClaudeCodeSkill的开源架构分析工具，通过八阶段工作流生成含Mermaid图的深度报告。其核心亮点为并行Subagent机制与覆盖率门控，专注揭示设计决策背后的权衡而非表层代码解读。工具支持三级分析模式，适用于代码接手与技术选型。建议用npx安装并搭配搜索MCP增强调研，但需注意洞察质量受限于模型认知上限。 综合评分： 65 文章分类： 产品介绍,AI安全,代码审计

repo-analyzer：一句话生成开源项目深度架构报告

原创

攻防路 攻防路

攻防录

2026年4月8日 10:44 北京

在小说阅读器读本章

去阅读

项目地址：https://github.com/yzddmr6/repo-analyzer

想搞清楚一个开源项目的架构，README 可获取信息有限。

代码摊开之后，你大概能知道它做了什么，但搞不清楚为什么这样设计、和同类项目相比差在哪、哪个模块是核心哪个是边角料。

repo-analyzer 是一款支持 Claude Code Skill，在 Claude Code 里说一句”分析项目 xxx”，它会自己克隆仓库、做外部调研、并行拆解每个模块，最后给你一份带 Mermaid 架构图的完整分析报告。

不只是”读 README”

市面上拿 AI 问”这个项目是干什么的”很常见。但 repo-analyzer 做的事情不是这个。

它的核心定位是架构级分析——不是告诉你”这个函数接收什么参数”，而是”为什么这里用了洋葱模型而不是线性管道”、”这个设计决策和 Fastify 相比有什么权衡”。

这一点从它的 SKILL.md 里写的第一条原则就能看出来：

从”这个项目解决什么问题”出发，不是”这个文件里有什么函数”。

用一个具体例子说明区别：

| 普通 AI 分析 | repo-analyzer 的要求 | | — | — | | handleRequest(ctx) 函数接收一个 Context 参数 | 请求进来后，系统会经过鉴权、限流、路由分发三个阶段 | | 路由系统采用了中间件模式，支持链式调用 | 路由系统选择了洋葱模型而非线性管道。线性管道实现更简单，但洋葱模型让每个中间件都能同时处理请求和响应阶段，这对日志、计时、错误恢复至关重要 |

这个差距不是靠调整 prompt 就能弥补的，而是整个分析工作流的设计方向不同。

工作流：8 个阶段，全程自动

repo-analyzer 本质上是一个 Claude Code 的 Skill 文件（SKILL.md 约 19KB），里面定义了一套完整的分析流程。安装后，你只需要说一句”分析项目 xxx”，它就会自动走完下面 8 个阶段：

阶段 1：项目获取 —— 解析输入（支持 owner/repo、GitHub/GitLab/Gitee URL、本地路径），git clone --depth=1，获取元数据

阶段 2：规模评估 —— 按模块统计有效代码行数（排除测试、构建配置、自动生成代码），让用户选择分析深度

阶段 3：外部调研 —— WebSearch 搜索项目评价、竞品对比、架构讨论，遍历官网关键页面，通读项目自带文档

阶段 4：自适应提问 —— 扫描目录结构和代码特征，生成针对性问题（每次不超过 3 个），与用户对齐分析方向

阶段 5：报告结构设计 —— 确定章节布局、模块叙事线，不用固定模板，按读者理解的最佳路径组织

阶段 6：并行深度分析 —— 为每个核心模块启动独立 Subagent，并行读代码，草稿写入 drafts/ 目录

阶段 7：交叉验证 —— 覆盖率门控，2-3 个关键结论逐行验证，跨模块结论交叉核对

阶段 8：多源融合 —— 把调研、模块草稿、洞察合并为连贯叙事，分段写入最终报告

三种分析深度可以选：

| 模式 | 核心模块覆盖率 | 次要模块覆盖率 | 适用场景 | | — | — | — | — | | 快速分析 | ≥30% | ≥10% | 快速了解项目全貌 | | 标准分析（推荐） | ≥60% | ≥30% | 常规架构分析 | | 深度分析 | ≥90% | ≥60% | 深入研究每个设计决策 |

覆盖率不是随便说说的。SKILL.md 里定义了严格的计算规则：只读了文件 30% 以下不算”已读”，大文件必须覆盖头部类型定义、核心业务逻辑、尾部测试代码三段。

并行 Subagent

阶段 6 是整个工作流里最有意思的设计。

常规做法是主 Agent 串行读每个模块，但对于几万行的大项目，这样太慢，而且读完前面忘后面。

repo-analyzer 的做法是：识别出 N 个核心模块后，为每个模块单独启动一个 Subagent，并行分析。每个 Subagent 的 prompt 里都带着：

1. 项目整体设计哲学（避免各模块分析变成孤立的代码说明书）
2. 叙事上下文（前一个模块讲了什么、读者带着什么问题进入本模块、本模块需要为下一个模块铺垫什么）
3. 覆盖率要求（达标标准写在 prompt 里，草稿末尾必须附覆盖率明细表）

主 Agent 在等待期间也没闲着——读项目文档、做调研、准备融合框架。

等所有 Subagent 完成（严禁提前合并），才进入验证和融合阶段。

报告输出

最终报告是单一 Markdown 文件，保存在：

~/repo-analyses/{项目名}-{日期}/ANALYSIS_REPORT.md

固定包含这几块内容（根据项目特点动态调整详略）：

• 问题引入 ——用具体场景讲清楚项目解决什么问题，现有方案哪里不够
• 竞品定位 ——设计哲学和技术路线差异，不是功能清单对比
• 项目全景 ——架构一览
• 深度模块分析 ——Why > What，每个设计决策的动机、权衡、替代方案代价
• 评价与启发 ——诚实的优缺点评估，读者能学到什么
• 架构图表 ——系统全局图 + 各模块流程图（Mermaid）

Mermaid 图表是贯穿全文的，不是最后加上去意思意思，而是配合每个模块的分析一起出现。

安装

三种方式，npx 最省事：

npx skills add yzddmr6/repo-analyzer

如果你用的是 Claude Code Plugin Marketplace：

/plugin marketplace add yzddmr6/repo-analyzer
/plugin install repo-analyzer@repo-analyzer

手动安装：

# macOS / Linux
git clone https://github.com/yzddmr6/repo-analyzer.git ~/.claude/skills/repo-analyzer

# Windows
git clone https://github.com/yzddmr6/repo-analyzer.git %USERPROFILE%\.claude\skills\repo-analyzer

安装完之后，在 Claude Code 里直接说就行：

分析项目 https://github.com/astral-sh/ruff
分析一下 ollama/ollama 这个仓库的架构
对比分析 express 和 fastify

也支持 owner/repo 简写和本地路径。触发词很多，自然语言说”看看这个库怎么实现的”也能激活。

使用场景

1. 快速上手陌生代码库

新同事入职、接手遗留项目、参与开源贡献前的预研，都可以先跑一遍深度分析，比自己一头扎进代码效率高得多。

2. 技术选型决策

比如你要在 Fastify 和 Express 之间选一个。跑一次对比分析，能看到两者在设计哲学、中间件实现、性能权衡上的本质差异，而不是仅仅对比 Star 数和文档质量。

3. 学习优秀项目的设计思想

不只是知道 Ruff 比 pylint 快，而是搞清楚它为什么快——Rust 实现、并行处理、增量分析各占几分，哪种设计是核心，哪种是锦上添花。

4. 写技术文章 / 分享

如果你要给团队做技术分享或者写文章介绍一个项目，这份报告可以直接作为素材底稿。

局限

这个 Skill 依赖 Claude Code 的内置工具就能跑。如果你接了 Tavily MCP 或 Brave Search MCP，外部调研能力会更强，但不装也不影响基本使用。

另外，分析深度和质量最终还是取决于模型本身——代码覆盖率的计算和跨模块验证做得再细，如果模型本身理解不到位，洞察的质量也会受限。这是当前所有 Skill/Prompt 工程的天花板，repo-analyzer 在框架层面已经把能做的都做了。

欢迎关注“攻防录”✨

免责声明：

本文所载程序、技术方法仅面向合法合规的安全研究与教学场景，旨在提升网络安全防护能力，具有明确的技术研究属性。

任何单位或个人未经授权，将本文内容用于攻击、破坏等非法用途的，由此引发的全部法律责任、民事赔偿及连带责任，均由行为人独立承担，本站不承担任何连带责任。

本站内容均为技术交流与知识分享目的发布，若存在版权侵权或其他异议，请通过邮件联系处理，具体联系方式可点击页面上方的联系我。

本文转载自：攻防录 攻防路 攻防路《repo-analyzer：一句话生成开源项目深度架构报告》