analyze-repo

リポジトリ分析

リポジトリのアーキテクチャ、依存関係の負荷、影響の大きい技術的負債を可視化する、単独で動作する HTML 監査レポートを作成します。すべての主張は、測定結果または特定のファイルを根拠とし、不確実な点は明示します。

ワークフロー

1. 根拠台帳を作成する

コマンドを選ぶ前に、リポジトリのガイダンスと環境を確認します。生成物、ベンダー提供のファイル、キャッシュ、依存関係のディレクトリはソースの指標から除外します。以下を収集します。

• リポジトリの構成：ソースファイル、言語、トップレベルのモジュール、エントリーポイント
• 組織構造：機能、レイヤー、パッケージの所有関係、ディレクトリ構成とランタイムおよびドメインモデルとの整合性
• 構成要素の連携：モジュール間の連携方法、インターフェースと接合点の配置、複雑さが一部に集中しているか、複数の呼び出し元に重複しているか
• アーキテクチャ：ランタイムの境界、データフロー、永続化、外部システム
• 依存関係：ファンインの大きいモジュール、依存関係の方向、接合点の違反、ツールで検証できる場合は循環依存
• パターン：確立されたフロントエンド、バックエンド、統合、状態管理、永続化、設計パターン、競合する実装、未完了の移行
• ホットスポット：サイズや複雑さの大きいファイル、複数の責務を持つファイル、TODO／FIXME の集中箇所
• 意思決定：既存の ADR と、リポジトリのドキュメントに根拠が記載されていない、重大な影響を伴う選択
• 検証：テストの配置場所、テストランナーの設定、カバレッジ成果物、CI チェック

件数やグラフに関する主張には、決定的なコマンドまたはプロジェクトのツールを使用します。以下のフィールドを含む根拠台帳を記録します。

フィールド	要件
主張	反証可能な記述を 1 つ
根拠	コマンド出力、設定、または正確なファイル／モジュールパス
方法	根拠の収集方法
確信度	verified、supported、または unverified

カバレッジ成果物または実行したカバレッジコマンドで測定値が得られた場合に限り、カバレッジを測定値として報告します。それ以外の場合はテストの状況を報告し、カバレッジを Not measured と記載します。

重大な影響を伴うアーキテクチャがある場合は、references/architecture-decisions.md を読み込みます。意思決定を未記録と判断する前に、既存の ADR と設計ドキュメントを検索します。観察された選択と推定した根拠は分けて記録し、把握できていないビジネス上の制約は所見ではなく質問として扱います。

有用な場合は、利用可能なサブエージェントの仕組みを通じて、リポジトリの広範な調査を委任します。調査担当には台帳のスキーマを伝え、内容がある各カテゴリについて具体的なパスを必ず示すよう求めます。返された主張の検証は親エージェントが行います。

完了条件：候補となるすべての所見に、根拠と確信度ラベルが付いていること。

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