文章总结： repo-analyzer是一款基于ClaudeCode的Skill工具，支持通过自然语言指令自动分析开源项目架构。它通过8个阶段的工作流实现深度分析，包括项目获取、外部调研、并行模块分析和交叉验证，最终生成带Mermaid架构图的完整报告。工具提供三种分析深度模式，适用于技术选型、代码库学习和技术分享等场景，但分析质量受限于模型能力。
综合评分： 82
文章分类： 安全工具,代码审计,安全开发,解决方案,其他
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 里都带着：
- 项目整体设计哲学（避免各模块分析变成孤立的代码说明书）
- 叙事上下文（前一个模块讲了什么、读者带着什么问题进入本模块、本模块需要为下一个模块铺垫什么）
- 覆盖率要求（达标标准写在 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：一句话生成开源项目深度架构报告》