repo-analyzer

Git プロジェクト深掘り分析スキル

オープンソースプロジェクトを深く分析し、専門的なアーキテクチャレポートを作成します。このレポートは深い洞察を含む技術調査であり、読み終えた読者がビジネス上の課題を理解し、アーキテクチャ設計を把握し、自分なりの考察を深められることを目指します。

使用する場面

• オープンソースプロジェクトのアーキテクチャや設計を分析する
• 同種のプロジェクトを2つ比較し、設計上の違いを分析する
• フレームワークやライブラリの実装方針を深く調査する

使用しない場面

• 単純なコードの問題やデバッグ
• 単一ファイルの分析やコードレビュー
• アーキテクチャレベルのコード変更を伴わない場合

出力言語

デフォルトは中国語です。ユーザーが別の言語で質問した場合は、ユーザーの言語に合わせます。

核心原則

1. ビジネスの視点を優先する

「このプロジェクトはどのような問題を解決するのか」から考え、「このファイルにどのような関数があるのか」から考えるのではありません。

避ける表現	使う表現
handleRequest(ctx) 関数は Context パラメーターを受け取ります……	リクエストを受け取ると、システムは認証、レート制限、ルーティングの3段階を経ます……
interface MessageQueue { push(); pop() }	モジュール間はメッセージキューで疎結合になっています。プロデューサーはメッセージを送ることだけに専念し、コンシューマーは優先順位に従ってメッセージを取得します。

2. 抽象度を適切に保つ：コードを貼らず、設計を語る

原則として、設計パターンやアーキテクチャのレベルで説明し、必要がない限り元のコードは掲載しません。フロー、ロジック、設計思想を際立たせ、コード断片ではなく、アーキテクチャ図（Mermaid）、フローチャート、表を使って表現します。コードを掲載するのは、設計が特に巧妙な場合、プロジェクト独自の概念を取り入れている場合、または実装が中心的なアピールポイントである場合に限ります。その場合も、必ず最初に自然言語で説明します。

3. 全体との関連付け

個々の分析はすべて、プロジェクト全体の設計思想と結び付ける必要があります。これこそが「コードの説明書」と「アーキテクチャ分析」を分ける重要なポイントです。詳しくは analysis-guide.md の全体との関連付けに関する章を参照してください。

4. 読者の気づきを促す文章

目標は、読者が学び、考えるきっかけを得ることであり、コードの説明書を提供することではありません。経験豊富なエンジニアがホワイトボードの前で解説するように、独自の見解、推論、比較を盛り込みます。詳しくは analysis-guide.md の読者の気づきを促す文章に関する章を参照してください。

5. 深い洞察：Why > What（必須）

すべての設計上の決定について、動機、トレードオフ、代替案のコストを説明する必要があります。「何であるか」の説明は出発点にすぎず、「なぜそうなのか」の説明こそが分析の価値です。各コアモジュールとアーキテクチャ全体について、次の問いに答えてください。

• なぜこの設計なのか？ 「どのパターンを使ったか」だけでなく、「なぜこの場面に適しているのか」を説明します。
• この設計でなければどうなるか？ 代替案のコストを説明します。
• 業界のベストプラクティスと比べてどうか？ 優れている点と改善の余地を説明します。
• 自分なら再設計をどうするか？ より深い理解を示します。
• 体系的な設計思想は何か？ プロジェクト全体に一貫するスタイル（例：「設定より規約」、「ゼロコスト抽象化」）を説明します。

例：

❌ ルーティングシステムはミドルウェアパターンを採用し、チェーン呼び出しをサポートしています。

✅ ルーティングシステムは、線形パイプラインではなくオニオンモデルを採用しています。線形パイプラインは実装がより単純ですが、オニオンモデルでは各ミドルウェアがリクエスト処理とレスポンス処理の両方を行えます。これはログ記録、計測、エラーからの復旧に欠かせません。Express は当初、線形モデルを採用しましたが、後にレスポンス後の処理にさまざまなハックが必要になりました。Koa はその教訓を踏まえ、オニオンモデルに移行しました。自分が再設計するなら、ミドルウェアの依存関係を宣言できる機能を追加し、フレームワークが自動で順序を決める方法を検討します。これは Fastify が採用している手法で、順序に起因する見つけにくいバグを防げます。

補足要件

• コードを根拠とする — すべての結論にコード上の根拠を持たせ、ファイルパス または ファイルパス:行番号の範囲 を明記します。曖昧な表現は禁止です。
• 人間味を持たせる — 経験豊富なエンジニアが新しい同僚にオンボーディングを行うように、主観的な評価や提案を加え、AIらしい決まり文句は避けます。
• 重要な箇所は深く、二次的な箇所は簡潔に — 中心的な革新点は深く分析し、汎用ユーティリティ関数は一言で済ませます。
• 批判的に考える — 業界の実践と比較し、実際の問題を指摘します。欠点を避けて通りません。参考資料は analysis-guide.md です。
• 流暢でわかりやすい文章にする — 全体を自然で流暢な文章にし、入門レベルのエンジニアにも理解でき、学びが得られるようにします。過度に学術的な表現や専門用語の羅列は避けます。
• 単なる羅列を避ける — 各モジュールでは深い詳細を示し、一言で済ませたり、一般論に終始したりしてはいけません。適切な場合は各モジュールに対応する Mermaid アーキテクチャ図を加え、読者が設計の要点から気づきや学びを得られるようにします。

分析ワークフロー

柔軟性の原則：以下の各段階や章はあくまで推奨事項であり、必ず厳密に実行すべきチェックリストではありません。agent は分析対象プロジェクトの特性に応じて判断してください。現在のプロジェクトに意味のない段階や手順は、省略または簡略化できます。最終的なレポートの品質を最優先します。

段階 1：プロジェクトの取得と初期化

1. ユーザー入力を解析します（owner/repo、GitHub/GitLab/Gitee の URL、ローカルパス、プロジェクト名に対応）。
2. 作業領域を作成します。ユーザーのホームディレクトリの下に repo-analyses/${REPO_NAME}-{YYYYMMDD} ディレクトリを作成し、$WORK_DIR とします（クロスプラットフォーム対応：macOS/Linux では $HOME、Windows では $USERPROFILE または $HOME を使用）。
3. ユーザーがローカルパスを指定した場合は clone を省略し、それ以外の場合は git clone --depth=1 でリポジトリをクローンします。
4. 基本的なメタデータ（Star、Fork、コントリビューター、コード統計）を取得します。

段階 2：プロジェクト規模の評価と分析モードの選択

1. 有効なコード行数を集計します（読み飛ばし可能なコードを除外）。モジュールごとの分布を一覧にします。
   • 読み飛ばし可能なコードの定義：テストコード、ビルド／デプロイ設定（Dockerfile、CI yaml など）、自動生成コード（protobuf 生成物、lock ファイルなど）、サンプル／ドキュメントのコード
   • find + wc -l や cloc などのツールを使って集計し、トップレベルディレクトリごとに分類します。
2. コード規模をユーザーに報告し、AskUserQuestion を使って分析モードを選んでもらいます。

モード	コアモジュールのカバレッジ	二次モジュールのカバレッジ	適した用途
クイック分析	≥30%	≥10%	プロジェクトの全体像を素早く把握する
標準分析（推奨）	≥60%	≥30%	一般的なアーキテクチャ分析
深掘り分析	≥90%	≥60%	各設計上の決定を深く調査する

3. コード規模の集計結果とユーザーが選んだ分析モードを drafts/03-plan.md に記録し、以降の段階で分析の深さを調整します。

カバレッジの計算ルール：

• カバレッジ = Read ツールで実際に要求した行範囲の和集合 / ファイルの総行数
• 大きなファイル（>500 行）は分割して読み取り、次の重要な箇所が網羅されていることを確認する必要があります。
  • ファイル冒頭の型定義とインポート（最初の 100 行）
  • コアとなるビジネスロジックの関数（ディレクトリ構成または関数名から特定）
  • ファイル末尾のテストコード（存在する場合）
• ファイルの一部（<30%）しか読んでいない場合はカバレッジに算入せず、「未読」とみなします。
• 自動生成コード（proto 生成物、lock ファイルなど）はカバレッジ要件を下げることができます。構成をスキャンすればよく、1行ずつ読む必要はありません。

段階 3：外部調査 + プロジェクトドキュメントの精読（まず検索してから読む）

1. WebSearch でプロジェクトの評価、比較、アーキテクチャに関する議論を検索します（少なくとも 3〜5 回）。
2. プロジェクトの公式サイトを確認します（存在する場合）。
   • README または GitHub ページから公式サイトの URL を取得します。
   • WebFetch/tavily_crawl を使って公式サイトの主要ページ（ホーム、Features、Use Cases、Comparison、Blog など）を確認します。
   • 重点的に確認する内容：製品の位置付けを示す文言（tagline）、典型的な利用場面、公式の競合比較、ユーザー事例／testimonials
   • 公式サイトの内容は「なぜこの製品が必要なのか」を理解するための最適な情報源であることが多く、コードや技術ドキュメントよりも直接的にその答えを示します。
3. プロジェクトに付属するドキュメントを通読します。
   • アーキテクチャドキュメント（architecture/、docs/、design/ などのディレクトリ）
   • CONTRIBUTING.md、AGENTS.md などの開発者向けガイド
   • RFC、ADR（Architecture Decision Records）、設計提案など
   • こうしたドキュメントには、開発者の設計意図、トレードオフ、過去の決定に至った背景が記載されていることが多く、「なぜこの設計なのか」を理解するための一次資料となります。
   • ドキュメントに記載された重要な設計上の決定や考え方を、調査ノートに抜き出します。
4. 調査で得た知見を整理して drafts/03-research.md に記録します。以下の構造化されたセクションを必ず含めます（情報が不足している場合は「見つからず」と記載します）。
   • プロジェクトが解決する中心的な課題：課題を1〜3個の具体的な場面で説明します（誰が、どのような状況で、どのような問題に直面し、既存の解決策ではなぜ不十分なのか）。
   • 競合／同種のプロジェクトとの比較：最も関連性の高い競合を3〜5個挙げ、それぞれの位置付けと技術方針の違いを説明します。
   • このプロジェクトを独立して開発する必要がある理由：既存の解決策を組み合わせて対応できないのか、このプロジェクト独自の価値提案は何かを説明します。
   • プロジェクトの背後にある組織的な動機（該当する場合）：営利企業の戦略的な考えや、オープンソースコミュニティにおけるエコシステム上の位置付けを説明します。
5. 分析計画を作成し、drafts/03-plan.md に記録します。

阶段 4: 项目特征识别 + 自适应提问

这是核心阶段。不使用固定问题列表，而是根据项目特征生成针对性问题。

步骤：

1. 快速扫描：扫描入口文件、目录结构、依赖声明、项目文档、README

2. 识别项目核心特征：

   • 项目类型与定位（库/框架/应用/工具）
   • 规模与成熟度
   • 设计风格信号（类型体操、极简 API、配置驱动等）
   • 技术栈特点（新兴技术、多语言、特定运行时）
   • 社区定位（核心基础设施、应用层工具、教学项目等）

3. 从特征中提炼问题：根据观察到的项目特征生成针对性问题。问题应该帮助聚焦分析方向，而不是走流程

   思维过程——每个观察都可能暗示一个值得问用户的问题：

   • 观察到的技术选择 → 问动机（不常见的技术组合？自己实现了通常用第三方库解决的功能？）
   • 观察到的架构特征 → 问优先级（性能优化痕迹？复杂的插件/扩展系统？）
   • 观察到的设计张力 → 问取舍（简单性 vs 灵活性？向后兼容的包袱？）
   • 观察到的项目定位 → 问受众（目标用户是谁？在生态中是替代还是填补空白？）

   维度启发——什么样的项目特征暗示什么样的分析角度：

   • 小而精的库 → API 设计哲学、边界划定；大型框架 → 模块化策略、向后兼容、生态治理
   • 使用新兴技术 → 为什么选择它、迁移成本；多语言/多范式 → 语言边界设计
   • 大量泛型/类型体操 → 类型安全 vs 复杂度权衡；极简 API → 简单性如何实现、牺牲了什么

   好问题的特征：具体（基于代码中观察到的现象）、有分析价值（答案会影响分析方向）、用户能答（问关注点和偏好，不问需要深入代码才能回答的技术细节）、不重复（不问通过代码就能回答的问题）

4. 向用户提问：使用 AskUserQuestion 工具向用户提问，每次不超过 3 个问题

   • 其中一个问题应确认报告开头的详略程度：对于知名项目，用户可能不需要冗长的产品介绍和竞品对比，只想直接进入代码分析。询问用户是否需要场景化引入和竞品定位章节，还是直接从项目全景和代码分析开始

5. 不限轮次：可多轮提问直到方向明确，分析过程中发现新的关键分歧点可以再追问

关键原则：问题完全由项目特征驱动，不预设类别。不同项目应该产生完全不同的问题。

阶段 5: 动态报告结构设计

根据用户回答 + 项目特征，设计本次报告的章节结构。

步骤：

1. 综合信息：结合阶段 3 的调研、阶段 4 的项目特征和用户回答
2. 设计章节结构：不使用固定模板，但必须满足骨架约束（见下方）
3. 输出报告大纲：将设计好的报告大纲输出给用户确认后再继续
4. 识别模块：追踪核心数据流，识别 N 个逻辑模块（按业务功能划分），分为核心模块和次要模块
5. 设计模块叙事线：确定模块在报告中的呈现顺序和过渡逻辑，不按目录结构排列，而是按读者理解的最佳路径组织：
   • 选择叙事主线：数据流驱动（请求从进入到离开经过哪些模块）、分层驱动（从底层到上层）、或问题驱动（从核心问题到解决方案逐层展开）
   • 每两个相邻模块之间写明过渡逻辑：上一个模块的输出/问题/局限 → 引出下一个模块的必要性
   • 将叙事线写入 drafts/05-modules-plan.md，格式示例：模块 A →[A 的输出需要 B 来消费]→ 模块 B →[B 解决了 X 但引出 Y 问题]→ 模块 C
6. 写入计划：输出模块清单和报告大纲写入 drafts/05-modules-plan.md

骨架约束（报告不规定具体章节，但必须满足）：

• 有场景化问题引入（用具体场景讲清楚项目解决什么问题、现有方案的不足、为什么需要这个项目——素材来自阶段 3 调研笔记）。注意：如果用户在阶段 4 表示不需要冗长介绍（如项目已经很知名），可以精简或跳过此章节，直接从项目全景开始
• 有竞品定位（与同类项目的关键差异，不是功能清单对比，而是设计哲学和技术路线的差异）。注意：同上，用户可选择跳过
• 有项目全景（让读者快速理解项目是什么、解决什么问题）
• 有深度分析（核心设计的 Why、权衡、与业界对比）
• 有评价与启发（诚实的优缺点、读者能从中学到什么）
• 有架构可视化（Mermaid 图表）
• 所有结论有代码依据

阶段 6: 并行深度分析（subagent 团队）

必须使用 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 中要求增量写入草稿：

• 每完成一个子系统/子模块的分析后，立即将该部分写入草稿文件
• 第一个子系统用 Write 创建文件，后续子系统用 Edit 追加
• 不要等全部文件读完再一次性写入
• 覆盖率明细表在最后追加

主 agent 等待纪律：

• subagent 启动后，主 agent 不得阅读 subagent 负责的源码文件
• 主 agent 在等待期间应专注于：阅读项目文档（architecture/、docs/）、外部调研、设计报告骨架、准备阶段 8 的融合框架
• 判断 subagent 是否卡住的标准：output 文件超过 5 分钟无新增行。只有确认卡住后，主 agent 才可以接管该模块的分析
• 严禁提前合并：必须等所有 subagent 全部完成后，再开始阶段 7 和阶段 8 的合并工作。不要在部分 subagent 还在运行时就开始写最终报告

阶段 7: 交叉验证 + 质量管控（主 agent）

7.1 覆盖率门控：

1. 读取每个 drafts/06-module-*.md 末尾的覆盖率明细表
2. 快速检查：每个草稿末尾是否有覆盖率表、合计行是否标注达标（✅/❌）
3. 只有标注 ❌ 或缺少覆盖率表的模块才需要深入检查
4. 不达标模块 → 主 agent 自动补充阅读未覆盖的关键文件，将补充发现追加到对应草稿
5. 补充后仍不达标 → 向用户报告哪些模块未达标及原因（如文件过大、二进制文件等）

7.2 抽查验证：

1. 从每个核心模块草稿中选取 2-3 个关键结论
2. 回到源码逐行验证结论准确性
3. 发现偏差则修正草稿中的对应内容

7.3 交叉验证：

1. 交叉验证【待主 agent 验证】标注的跨模块结论
2. 综合回答探索问题，识别跨模块设计模式
3. 验证全局关联：每个模块的分析是否都连接到了项目整体设计哲学
4. 写入 drafts/07-cross-validation.md

阶段 8: 多源融合与最终报告（主 agent）

1. 提炼架构洞察和系统性设计哲学
2. 基于阶段 3 调研结果深化竞品对比（仅在阶段 3 信息不足时补充搜索）
3. 提出"如果重新设计"的改进建议
4. 写入 drafts/08-insights.md
5. 多源融合：以阶段 5 设计的报告章节结构为骨架，从各草稿中抽取内容填充。同一概念在多个草稿中出现时，取最详细版本并补充其他版本独有信息。融合后消除所有"见草稿 X"、"详见附录"等跳转指示
   • 叙事连贯：按阶段 5 设计的叙事线组织模块章节。每个模块章节的开头必须有 1-2 句过渡，连接上一个模块的结论或问题。避免"接下来我们分析 X 模块"这种生硬转折，改用自然过渡（如"Gateway 完成了请求的认证和路由，但它只负责'谁可以进来'，不负责'进来之后能做什么'。这个行为控制的职责，由策略引擎承担。"）
6. 分段写入：最终报告通常超过 500 行，先 Write 前几个章节（200-300 行），后续用 Edit 追加，每次追加前 Read 确认末尾位置
7. 覆盖率汇总：将覆盖率数据汇总写入 drafts/08-coverage.md（不放入最终报告）
   • 数据直接从各 subagent 草稿末尾的覆盖率明细表中提取，不需要主 agent 重新计算
   • 如果主 agent 在阶段 7 补充了阅读，将补充的行数加到对应模块的「已读行数」中
   • 汇总表格式：

模块	类型	文件数	有效代码行	已读行数	覆盖率	达标
...	核心/次要	...	...	...	...%	✅/❌

8. 汇总生成最终报告（不包含覆盖率章节）

草稿文件清单

所有中间过程保存到 $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。

特殊场景

• 超大型项目（>50000 行）：优先分析核心模块，使用 Agent 并行分析
• 对比分析模式：两个项目分别完成阶段 1-4，然后在阶段 5 设计对比式报告结构，骨架约束中增加"设计决策对比"和"选型建议"

输出要求

1. 最终报告为单一 markdown 文件：$WORK_DIR/ANALYSIS_REPORT.md
2. 大量使用 Mermaid 图表展示架构、流程、数据流
3. 面向需要理解业务架构的开发者
4. 亮点和问题的评价思维框架参考 analysis-guide.md
5. 分析哲学和深度标准参考 analysis-guide.md