From repo-analyzer
Deeply analyzes open-source Git repositories, generating architecture reports with business insights, design rationale, Mermaid diagrams, and critical evaluations. Use for studying frameworks, comparing projects, or architecture research.
How this skill is triggered — by the user, by Claude, or both
Slash command
/repo-analyzer:repo-analyzerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
深度分析开源项目并生成专业架构报告。报告是有深度洞察的技术研究,读完后读者能理解业务问题、掌握架构设计、产生自己的思考。
深度分析开源项目并生成专业架构报告。报告是有深度洞察的技术研究,读完后读者能理解业务问题、掌握架构设计、产生自己的思考。
默认中文。如果用户使用其他语言提问,则跟随用户语言。
从"这个项目解决什么问题"出发,不是"这个文件里有什么函数"。
| 不要 | 要 |
|---|---|
handleRequest(ctx) 函数接收一个 Context 参数... | 请求进来后,系统会经过鉴权、限流、路由分发三个阶段... |
interface MessageQueue { push(); pop() } | 模块间通过消息队列解耦,生产者只管投递,消费者按优先级拉取 |
默认在设计模式和架构层面描述,非必要情况下不贴原始代码。重点突出流程、逻辑、设计思想,用架构图(Mermaid)、流程图、表格来表达,而非代码片段。只有设计特别精妙、项目自创独特概念、或实现是核心卖点时才展示代码,且必须先用自然语言解释。
每个局部分析都必须连接到项目整体设计哲学——这是区分"代码说明书"和"架构分析"的关键。详见 analysis-guide.md 的全局关联章节。
目标是让读者学到东西、产生思考,而不是获得一份代码说明书。像资深工程师在白板前讲解——有观点、有推理、有对比。详见 analysis-guide.md 的启发性写作章节。
每个设计决策必须解释动机、权衡、替代方案代价。描述"是什么"只是起点,解释"为什么"才是分析的价值所在。每个核心模块和整体架构都要回答:
示例:
❌ 路由系统采用了中间件模式,支持链式调用。
✅ 路由系统选择了洋葱模型而非线性管道。线性管道实现更简单,但洋葱模型让每个中间件都能同时处理请求和响应阶段——这对日志、计时、错误恢复至关重要。Express 当年选择线性模型,后来不得不用各种 hack 处理响应后逻辑,Koa 吸取教训才转向洋葱模型。如果让我重新设计,我会考虑加入中间件依赖声明,让框架自动排序——这是 Fastify 的做法,能避免顺序导致的隐蔽 bug。
文件路径 或 文件路径:行号范围,禁止模糊表述灵活性原则:以下所有阶段和章节都是建议性的指引,不是必须严格执行的清单。agent 应根据当前分析的项目特性动态决策——如果某个阶段或环节对当前项目没有意义,可以跳过或简化。一切以最终报告的质量为准。
owner/repo、GitHub/GitLab/Gitee URL、本地路径、项目名称)repo-analyses/${REPO_NAME}-{YYYYMMDD} 目录作为 $WORK_DIR(跨平台:macOS/Linux 使用 $HOME,Windows 使用 $USERPROFILE 或 $HOME)git clone --depth=1 克隆仓库find + wc -l 或 cloc 等工具统计,按顶层目录分组| 模式 | 核心模块覆盖率 | 次要模块覆盖率 | 适用场景 |
|---|---|---|---|
| 快速分析 | ≥30% | ≥10% | 快速了解项目全貌 |
| 标准分析(推荐) | ≥60% | ≥30% | 常规架构分析 |
| 深度分析 | ≥90% | ≥60% | 深入研究每个设计决策 |
drafts/03-plan.md,后续阶段据此控制分析深度覆盖率计算规则:
architecture/、docs/、design/ 等目录)drafts/03-research.md,必须包含以下结构化段落(信息不足则标注"未找到"):
drafts/03-plan.md这是核心阶段。不使用固定问题列表,而是根据项目特征生成针对性问题。
步骤:
快速扫描:扫描入口文件、目录结构、依赖声明、项目文档、README
识别项目核心特征:
从特征中提炼问题:根据观察到的项目特征生成针对性问题。问题应该帮助聚焦分析方向,而不是走流程
思维过程——每个观察都可能暗示一个值得问用户的问题:
维度启发——什么样的项目特征暗示什么样的分析角度:
好问题的特征:具体(基于代码中观察到的现象)、有分析价值(答案会影响分析方向)、用户能答(问关注点和偏好,不问需要深入代码才能回答的技术细节)、不重复(不问通过代码就能回答的问题)
向用户提问:使用 AskUserQuestion 工具向用户提问,每次不超过 3 个问题
不限轮次:可多轮提问直到方向明确,分析过程中发现新的关键分歧点可以再追问
关键原则:问题完全由项目特征驱动,不预设类别。不同项目应该产生完全不同的问题。
根据用户回答 + 项目特征,设计本次报告的章节结构。
步骤:
drafts/05-modules-plan.md,格式示例:模块 A →[A 的输出需要 B 来消费]→ 模块 B →[B 解决了 X 但引出 Y 问题]→ 模块 Cdrafts/05-modules-plan.md骨架约束(报告不规定具体章节,但必须满足):
必须使用 Agent 工具并行启动 subagent。参考 module-analysis-guide.md 中的 prompt 模板和协作规范。
每个 subagent 的 prompt 中必须包含项目整体设计哲学和全局视角要求,确保模块分析不是孤立的。
每个 subagent 的 prompt 中还必须包含该模块的叙事上下文(来自阶段 5 的叙事线设计):前一个模块讲了什么、读者带着什么问题进入本模块、本模块需要为下一个模块铺垫什么。subagent 应在草稿开头用 1-2 句衔接前一模块,草稿结尾用 1 句铺垫下一模块。
每个 subagent 的 prompt 末尾必须附加覆盖率要求(参考 module-analysis-guide.md 中的覆盖率要求段落),告知当前分析模式和最低覆盖率目标,要求草稿末尾附覆盖率明细表。
subagent 写入策略: 对于大模块(文件总行数 > 5000 行),必须在 subagent prompt 中要求增量写入草稿:
主 agent 等待纪律:
7.1 覆盖率门控:
drafts/06-module-*.md 末尾的覆盖率明细表7.2 抽查验证:
7.3 交叉验证:
drafts/07-cross-validation.mddrafts/08-insights.mddrafts/08-coverage.md(不放入最终报告)
| 模块 | 类型 | 文件数 | 有效代码行 | 已读行数 | 覆盖率 | 达标 |
|---|---|---|---|---|---|---|
| ... | 核心/次要 | ... | ... | ... | ...% | ✅/❌ |
所有中间过程保存到 $WORK_DIR/drafts/:
| 阶段 | 文件 |
|---|---|
| 3 | 03-research.md, 03-plan.md |
| 5 | 05-modules-plan.md |
| 6 | 06-module-{name}.md(subagent 生成) |
| 7 | 07-cross-validation.md |
| 8 | 08-insights.md, 08-coverage.md |
文件写入分块,单次不超过 300 行或 15KB。
$WORK_DIR/ANALYSIS_REPORT.mdnpx claudepluginhub yzddmr6/repo-analyzer --plugin repo-analyzerMaps codebase architecture, layers, dependencies, and tech debt hotspots then generates a visual HTML report with a Mermaid diagram and opens it for review.
Builds and maintains ARCHITECTURE.md and DETAILED_DESIGN.md incrementally with coverage tracking. Principal mode analyzes vision, bottlenecks, gaps, and alternatives.
Deeply explores existing codebases to map architecture, data flow, domain model, API surface, dependencies, and code health using read-only SubAgents.