software-architecture-analysis

ソフトウェアアーキテクチャ分析 — コードベースのリバースエンジニアリングから設計書へ

使用する場面

• 参考実装があり、設計のヒントを得るためにそのアーキテクチャを理解する必要がある場合
• 同じ問題領域のシステムについて、PRD、設計書、または仕様書が必要な場合
• 出力をクリーンルームにする必要がある場合：参考コードベースからソースコードのサンプルを一切コピーしない
• 参考実装とは異なるアーキテクチャ上の制約（ローカルファースト、プライバシーファースト、セルフホスト可能）を持つシステムを設計する場合
• 正式なプロバイダー抽象化を設計するために、暗黙の契約、つまりコードベースが実行するストレージ操作を抽出する必要がある場合
• リポジトリの証拠に基づき、アーキテクチャの健全性、結合度、モジュール性、データの所有権、分散ワークフロー、境界変更への対応状況を評価する必要がある場合

次の場合には使用しないでください： グリーンフィールドまたは先を見越したアーキテクチャ設計（software-architectureを案内してください）、直接的なコードレビュー、バグ調査、セキュリティ監査。API／インターフェースのセマンティクスはapi-design-and-evolutionへ、データプラットフォーム戦略はdata-architectへ、実装は該当するエンジニアリングスキルへ、デプロイ基盤はplatform-engineeringへ、承認済みのシステム横断移行の実行はmigration-engineeringへ案内してください。

構築ワークフロー

Phase 1: Clone + Map  →  Phase 2: Find Key Files  →  Phase 3: Map Architecture
                                                              ↓
Phase 6: Constraint Redesign  ←  Phase 5: Write Spec  ←  Phase 4: Feature Inventory
                                                              ↓
                                                      Phase 7: QA

フェーズ1：リポジトリのクローンと構造のマッピング

シャロークローンで対象のリポジトリをクローンします：

git clone --depth=1 https://github.com/owner/repo /tmp/target-repo

トップレベルのディレクトリ構造をマッピングします。各ディレクトリについて、次を特定します：

• 使用している言語／フレームワーク
• フロントエンド、バックエンド、サービス、ファームウェア、サポートのいずれか
• コアコンポーネント（ビジネスロジック）か、サポート（CI、ドキュメント、ツール）か

ls -la /tmp/target-repo/
find /tmp/target-repo -type f -name "*.swift" | sort   # or *.py, *.rs, *.ts, *.go

フェーズ2：主要なアーキテクチャファイルの特定

行数で並べ替えて、最も大きなファイルを見つけます。これらのファイルにコアロジックが含まれています：

wc -l /tmp/target-repo/**/*.swift /tmp/target-repo/**/**/*.swift 2>/dev/null | sort -n

上位15～25個のファイルを、次の優先順位で読みます：

1. エントリーポイント：main、App、bootstrap — アプリの起動方法
2. データモデル：システム内を流れる型
3. コアサービス：キャプチャ、処理、ストレージのパイプライン
4. UI／ページファイル：ユーザー視点での機能の表面
5. 設定：環境ファイル、設定用構造体 — 外部依存関係
6. プライバシーに関わるファイル：ユーザーデータにアクセスするサービス

フェーズ3：アーキテクチャのマッピング

各コアサービスについて、次を特定します：

• 何をキャプチャするか：データの種類、ソース、頻度、保存場所
• どこで処理するか：ローカルかクラウドか、呼び出すAPI／サービス
• どこに保存するか：ローカルデータベース、クラウドデータベース、ファイルシステム
• 外部依存関係：すべてのサードパーティサービス、APIキー、クラウドプロバイダー
• プライバシープロファイル：どのデータが、どのような条件でマシンの外部に送信されるか

Mermaid構文を使って図を作成します（GitHubやほとんどのMarkdownエディターでネイティブにレンダリングされます）：

graph TD
    subgraph Capture["Capture Layer"]
        CAM[Camera/Mic Capture]
        FS[File Scanner]
    end

    subgraph Processing["Processing Layer"]
        OCR[OCR/NLP]
        STT[Speech-to-Text]
    end

    subgraph Storage["Storage Layer"]
        DB[(Local Database)]
        CLOUD[(Cloud Sync)]
    end

    CAM --> OCR
    FS --> OCR
    STT --> DB
    OCR --> DB
    DB --> CLOUD

    style Capture fill:#0a1a2e,stroke:#22d3ee
    style Processing fill:#0a2a1a,stroke:#34d399
    style Storage fill:#1a0a3a,stroke:#a78bfa

クラウドとローカルの境界にはサブグラフを使用します。すべての図のコードブロックでは必ず```mermaidを使用してください。ASCIIのボックス図や画像ファイルは使用しないでください。

アーキテクチャの根拠を分析する視点

最初のマップを作成した後は、質問に必要な参照資料だけを読み込みます。

• 観察されたシナリオ、制御、運用上の根拠から品質特性を推定する場合は、アーキテクチャ特性の分析を参照します。
• 境界、変更の伝播、モジュール性、デプロイ形態、または分解の準備状況を比較する場合は、結合度、モジュール性、分解を参照します。目標とする境界を決める前に、静的、動的、データ、時間、デプロイ、組織の各結合度を評価します。
• データの権限、分散トランザクション、オーケストレーション／コレオグラフィ、障害処理、または照合を追跡する場合は、データの所有権とワークフローの分析を参照します。
• 成果物が再利用可能な健全性レポートや構造化された引き継ぎ資料の場合は、アーキテクチャ健全性評価テンプレートを参照します。

すべての主張を観察済み、推定、報告済み、または不明として扱います。根拠となる成果物、トレース、設定、テスト、メトリクス、またはインタビューの証拠を引用します。観察されていないことを、不確実性を明記せずに欠陥とみなしてはいけません。

フェーズ 3b：インターフェース抽出パターン（DAO／プロバイダーコントラクトの設計）

暗黙のコントラクト、つまり、このコードベースがデータベースまたはストレージ層に必要とする操作を抽出することが目的の場合は、次の手順に従います。

ステップ 1 — まず設計思想を読む

コードに触れる前に、PHILOSOPHY.md、DESIGN.md、ARCHITECTURE.md、またはメインの README を読みます。これらには、インターフェースが守るべき設計上の制約が記載されています。たとえば、cashew の thought-graph ライブラリの PHILOSOPHY.md には「シンプルなグラフ、賢い推論レイヤー」とあります。エッジには型ラベルがなく、ノード型は LLM に対する説明的なヒントであり、グラフエンジンの操作を支えるものではありません。この制約をコントラクトに組み込む必要があります。

ステップ 2 — すべてのストレージ操作を一覧にする

ストレージ層（データベース、ファイルシステム、外部サービス）に触れるすべてのファイルを読みます。ファイルごとに、それぞれ異なる操作をすべて一覧にします。

カテゴリ	操作の例
ノード CRUD	作成、読み取り、更新、削除、スキャン、件数取得
エッジ CRUD	create_edge、get_neighbors、delete_incident
ベクトル KNN	find_similar、set_embedding、delete_embedding
グラフの走査	bfs、shortest_path、trace_derivation
保守	similarity_candidates、random_sample、get_metrics
トランザクション	開始、コミット、ロールバック

命名規則に基づいて対象ファイルを特定します：db.py、store.py、storage.py、embedding.py、session.py、persist.py、およびバッチ／保守用のモジュール。

ステップ 3 — 境界の漏れを示す回避策を特定する

アプリケーションロジックではなく、基盤の制約があるために存在するコードを特定します。次のような兆候があります。

• デュアルライトのパターン（異なるクエリ経路のために、同じデータを 2 つのテーブルに書き込む）
• 次元の不一致の検出とフォールバックの連鎖
• ネイティブ基盤で対応できる操作のために、テーブル全体を numpy/scipy に読み込む
• SQL でグラフ走査を再実装する再帰的な CTE
• 高速経路とフォールバック経路を切り替える try/except
• 「X は Y をネイティブでサポートしていないため必要」といったコメント

これらの回避策は、現在の境界の位置が不適切であることによるコストです。コントラクトの背後に移す候補となります。

ステップ 4 — 一覧を基にコントラクトを設計する

ステップ 2 のすべての操作を取り込み、ステップ 3 の基盤固有の詳細を漏らさない抽象インターフェース（ABC、Protocol、または trait）を定義します。

設計原則：

• 現在の基盤ができることではなく、コードベースが必要とすることを基準に設計します。
• 設計思想をインターフェースの制約とします。
• コストの高い操作（類似性検索、グラフ走査、スキャン）がパフォーマンス特性を決めます。コントラクトでは、ネイティブ基盤上でこれらを効率的に実装できるようにする必要があります。
• トランザクションは明示的にします。

ステップ 5 — 2 つのプロバイダーによる検証

抽象化をテストするために、2 つ目のプロバイダー実装を設計します。本番環境で使える品質である必要はありません。同じテストスイートに合格すれば十分です。2 つのプロバイダーによる検証では、次の問題を検出できます。

• 元の基盤のセマンティクスに特化しすぎた操作
• 2 つ目のプロバイダーで必要になる操作の不足
• 契約の漏出（データクラスを返す代わりに、SQL のカーソルのような動作を前提とするメソッドシグネチャ）

cashew の思考グラフライブラリを使用した詳しい例については、references/interface-extraction-pattern.md を参照してください。これは、5 つのステップすべてを実演する実際のオープンソースプロジェクトです。

フェーズ 4：機能一覧の作成

UI のビュー、ページ、オンボーディング画面のファイルを読み、ユーザー向け機能をすべて整理します。カテゴリごとに分類します。

• キャプチャ：録音、スキャン、インポート
• 処理：文字起こし、OCR、分析
• AI：チャット、アシスタント、インサイト、おすすめ
• ストレージ：ローカル、クラウド、エクスポート
• 連携：サードパーティサービス、API
• プラグイン：拡張機能、カスタムツール、MCP

フェーズ 5：クリーンルーム仕様の作成

これは最も重要なフェーズです。 出力ドキュメントでは、次の要件を満たす必要があります。

1. ソースコードを引用または再現せずに、アーキテクチャパターンを説明する
2. コンポーネント間の連携方法を自然言語で説明する
3. 行番号や変数名ではなく、アーキテクチャ層を使って元のコードベースを参照する
4. ソースコードの断片を一切含めない — Swift、Rust、Python、その他参照元のコードは含めません。仕様は派生作品ではなく、新しいコードを対象とします

「汚染させない」原則： 出力に参照元から識別できるコードパターンが含まれている場合は、より高い抽象度で書き直してください。

出力は、次のセクションで構成します。

• 製品ビジョンと設計原則
• アーキテクチャ概要（Mermaid 図）
• 機能要件（番号付き）
• 非機能要件（パフォーマンス、バッテリー、プライバシー）
• 技術アーキテクチャ（テクノロジーを含むコンポーネント一覧）
• プラグイン／拡張 API 仕様
• プライバシーアーキテクチャの詳細（データフローマップ）
• リリース基準（MVP → v1 → v2）

図のルール：

• すべての図に ```mermaid コードブロックを使用します — ASCII のボックス描画や画像ファイルは使用しません
• データフロー図は、1 つの巨大な図にまとめず、パイプラインごとに別々の Mermaid ブロックにします
• 外部依存関係には、それぞれ代替となるオープン標準を明記します（例：「OpenAI 互換 API により、任意のプロバイダーを利用可能」）

フェーズ 6：制約の見直し

新しい設計制約（ローカルファースト、プライバシーファースト）のもとでシステムを再構想する際は、次の点に従います。

1. 参照アーキテクチャにおける必須のクラウド依存関係をすべて特定する
2. それぞれについて、ローカルでの代替手段を特定する（クラウド API → ローカルモデル、Firestore → SQLite など）
3. ローカルとクラウドの両方をサポートするインターフェースについては、オープン標準を明記する（OpenAI 互換 API、S3 互換ストレージ、Whisper 互換 STT）
4. 参照元でプライバシーを侵害するパターン（ブラウザーの Cookie へのアクセス、他のアプリのデータを SQLite から直接読み取ることなど）が使われている場合は、禁止された手段として明記します。新しい設計では、適切な API（OAuth、プラットフォーム API、公式 SDK）を使う必要があります

フェーズ 7：納品後の QA

設計ドキュメントの納品後、次の確認を行います。

1. リンクの整合性を確認する — ドキュメントが他の設計ドキュメントを参照している場合は、相互リンクがあることを確認します。Markdown のリンクチェッカーを実行し、リンク切れを検出します。
2. 図の表示を確認する — すべての ```mermaid ブロックが表示されることを確認し、ASCII のボックス描画文字（┌、├、└、┐、┤、┘、┴、┬、┼）が出力に残っていないことを確認します。
3. コードの汚染を確認する — 参照元に由来すると思われるインラインのソースコードの断片がないか調べます。見つかった場合は、アーキテクチャレベルの説明に書き直します。
4. 相互参照を監査する — あるセクションで導入されたすべての概念が、別のセクションの実装と結び付いていることを確認します。ドキュメント内で一貫性が保たれている必要があります。

完了基準

依頼されたアーキテクチャ成果物が存在し、エビデンス台帳で事実と推論、未知の事項が区別され、クリーンルームチェックでコピーされた実装資料が見つからず、リンクされた参考資料が参照可能で、出力に隣接するスキルとの境界が明記されていれば、このスキルは完了です。ユーザーが別途許可しない限り、実装や移行の実行を提案する前に停止してください。

参考資料

• references/interface-extraction-pattern.md — cashew の思考グラフライブラリ（MIT、GitHub で公開）を使用した、Phase 3b のインターフェース抽出パターンの完全な実例です。ストレージバックエンドを差し替え可能なコードベースで、プロバイダー抽象化または DAO コントラクトを設計する際に参照してください。
• references/architecture-characteristics-analysis.md — エビデンスに基づく品質特性とシナリオ分析です。
• references/coupling-modularity-and-decomposition.md — 6 つの結合性の観点、モジュール性のシグナル、分解準備状況の評価です。
• references/data-ownership-and-workflow-analysis.md — データの権限、トランザクション／ワークフローのトポロジー、障害、照合の分析です。
• templates/architecture-health-assessment.md — 再利用可能なアーキテクチャ健全性レポートのテンプレートです。