SourceAtlas: スマートな時系列分析 (Git履歴)

Constitution: ANALYSIS_CONSTITUTION.md v1.0

コンテキスト

分析スコープ: $ARGUMENTS (デフォルト: リポジトリ全体) 目標: Git履歴から実行可能な洞察を抽出する 時間制限: 5～10分 前提条件: code-maat (不足している場合は許可を求めます)

クイックスタート

1. キャッシュを確認 (--force フラグが存在する場合はスキップ)
2. code-maat インストールを確認 (必要に応じて許可を得てインストール)
3. Git ログを生成 (過去12ヶ月、code-maat対応形式)
4. 分析を実行: ホットスポット、結合度、コントリビューター
5. リスク評価 (すべての次元を組み合わせ)
6. レポートを生成 (output-template.mdに従う)
7. 出力を検証 (verification-guide.mdを使用)
8. 自動保存 を .sourceatlas/history.md に

あなたのタスク

Git コミット履歴を分析して以下を理解します:

1. ホットスポット - 最も頻繁に変更されたファイル (複雑/リスクが高い可能性)
2. 時間的結合度 - 一緒に変更されるファイル (隠れた依存関係)
3. 最近のコントリビューター - どのエリアの知識を誰が持っているか (バスファクター)
4. リスク領域 - 優先順位付けのための総合評価

発見できること

分析タイプ	洞察	ビジネス価値
ホットスポット	複雑性インジケーター	リファクタリング優先度、技術的債務
結合度	隠れた依存関係	アーキテクチャレビューの対象
コントリビューター	知識の分布	バスファクターのリスク、教育の必要性
リスク	総合評価	リソース配分の意思決定

---

コアワークフロー

以下のステップを順番に実行します。詳細は workflow.md を参照してください。

ステップ0: 前提条件を確認 (30秒)

目的: code-maat がインストールされており、Java が利用可能であることを確認します。

code-maat を確認:

if [ -f "$HOME/.sourceatlas/bin/code-maat-1.0.4-standalone.jar" ]; then
  export CODEMAAT_JAR="$HOME/.sourceatlas/bin/code-maat-1.0.4-standalone.jar"
fi

見つからない場合は AskUserQuestion を使用:

• 「分析に code-maat が必要です。今すぐインストールしますか? (Java 8+ が必須)」
• はい → ./scripts/install-codemaat.sh を実行
• いいえ → 手動インストール手順を表示

→ workflow.md#step-0 を参照

ステップ1: Git ログを生成 (1分)

目的: code-maat 対応形式の Git ログファイルを作成します。

デフォルト: 過去12ヶ月

git log --all --numstat --date=short \
    --pretty=format:'--%h--%ad--%aN' \
    --after="$(date -v-12m +%Y-%m-%d)" \
    > /tmp/git-history.log

スコープを指定した場合: ディレクトリでフィルター (例: "src/")

→ workflow.md#step-1 を参照

ステップ2: ホットスポット分析 (2分)

目的: 頻繁に変更されるファイルを特定します。

code-maat revisions を実行:

java -jar "$CODEMAAT_JAR" -l /tmp/git-history.log -c git2 -a revisions

複雑性スコアを計算: LOC × リビジョン数

トップ10のホットスポットを特定 (複雑性でソート)

→ workflow.md#step-2 を参照

ステップ3: 時間的結合度分析 (2分)

目的: 一緒に変更されるファイルを検出します。

code-maat coupling を実行:

java -jar "$CODEMAAT_JAR" -l /tmp/git-history.log -c git2 -a coupling

重要な結合度でフィルター: degree ≥ 0.5

分類: 予期されるもの vs 疑わしいもの

→ workflow.md#step-3 を参照

ステップ4: 最近のコントリビューター分析 (2分)

目的: モジュール全体の知識分布をマップします。

code-maat entity-ownership を実行:

java -jar "$CODEMAAT_JAR" -l /tmp/git-history.log -c git2 -a entity-ownership

エリア別の知識マップを生成 (src/api/, src/core/ など)

バスファクターリスクを特定: 単一コントリビューターのモジュール

→ workflow.md#step-4 を参照

ステップ5: リスク評価 (1分)

目的: すべての次元を実行可能な優先度に組み合わせます。

複合リスクを計算: (リビジョン数 × 結合度_カウント) / コントリビューター_カウント

リスクカテゴリ:

• バスファクターリスク
• 複雑性リスク
• 結合度リスク
• テストギャップリスク

→ workflow.md#step-5 を参照

---

出力フォーマット

分析は以下の Markdown 構造に従います:

🗺️ SourceAtlas: History
───────────────────────────────
📜 [リポジトリ名] │ [N] ヶ月

**分析期間**: [開始] → [終了]
**分析済みコミット**: [カウント]
**分析済みファイル**: [カウント]

## 1. ホットスポット (トップ10)
[ランク、ファイル、変更数、LOC、複雑性スコアのテーブル]
[洞察パラグラフ]

## 2. 時間的結合度 (重要なペア)
[ファイルA、ファイルB、結合度、共変更のテーブル]
[予期されるものvs疑わしい結合度の分析]

## 3. 最近のコントリビューター (知識マップ)
[エリア別テーブル (コントリビューター、コミット、最後のアクティビティ)]
[バスファクターリスク セクション]

## 4. リスク概要
[リスク集約テーブル]
[優先アクション 番号リスト]

## 5. 推奨事項
[リファクタリング候補、知識共有、アーキテクチャレビュー]

## 次のステップを推奨
[見つけたものに基づく動的な提案]

→ output-template.md で完全な仕様と例を参照

---

重要なルール

1. プライバシーに配慮

• 「所有権 %」ではなく「最近のコントリビューター」を使用
• 知識分布に焦点を当てる、責任追及ではなく
• 見つけたものを機会として提示、批判ではなく

2. 実行可能な洞察

• すべての見つけたものに推奨アクションが必須
• 特定のコミットカウントとファイルパスを参照
• 具体的な次のステップ (曖昧な提案ではなく)

3. エビデンスベース

• すべてのホットスポットファイルが存在すること (確認)
• コミットカウントが Git 履歴と一致 (±20%の許容度)
• コントリビューター名が git log に含まれること

4. 時間制限

• デフォルト: 12ヶ月 (良いバランス)
• 最小: 3ヶ月 (有意なパターン用)
• 最大: 24ヶ月 (古い履歴を避ける)

5. 検証が必須

• 分析後に verification-guide.md を実行
• ファイルパス、コミットカウント、コントリビューターを検証
• 出力前に矛盾を修正

6. 憲法遵守

ANALYSIS_CONSTITUTION.md に従う:

• 第I条: エビデンスベース (すべての主張が git/code-maat から)
• 第III条: 検証 (V1-V4チェック実行)
• 第IV条: エビデンス形式 (file:line 参照)
• 第V条: 透明性 (分析期間、キャッシュ年齢を表示)
• 第VII条: ユーザーエンパワーメント (実行可能な推奨事項)

---

自己検証

分析を生成した後、検証ステップを実行します:

ステップV1: 検証可能な主張を抽出

出力をパースしてすべての定量的な主張を探す:

• ファイルパス (ホットスポット、結合ファイル)
• コミットカウント (合計、ファイルごと、コントリビューターごと)
• コントリビューター名
• 結合ペア
• 日付範囲

ステップV2: 並列検証

• ホットスポットファイルが存在することを確認 (3～5をサンプル)
• コミットカウントを確認 (±20%の許容度)
• Git 履歴でコントリビューターを確認
• 結合ペアを確認 (両方のファイルが存在)
• リポジトリ履歴内で日付範囲を確認

ステップV3: 結果を処理

• ✅ すべてのチェック合格 → 出力に進む
• ⚠️ 軽微な問題 (1～2 チェック) → 修正して記録
• ❌ 重大な問題 (3+ チェック) → 分析を再実行

ステップV4: 検証概要を追加

verification_summary:
  checks_performed: [...]
  confidence_level: "high"  # high|medium|low
  notes: [...]

→ verification-guide.md で完全なチェックリストを参照

---

高度な機能

キャッシュ動作

• デフォルト: キャッシュが存在すれば使用
• Force フラグ: --force でキャッシュをスキップ
• キャッシュ位置: .sourceatlas/history.md (固定パス)
• キャッシュ年齢警告: 30日以上古い場合

→ reference.md#cache-behavior を参照

自動保存メカニズム

検証後、完全な Markdown レポートが自動保存:

💾 .sourceatlas/history.md に保存されました

→ reference.md#auto-save-behavior を参照

次のコマンドへのハンドオフ

見つけたものに基づいて以下を提案:

• 高リスクのホットスポット → /sourceatlas:impact "[ホットスポット]"
• 疑わしい結合度 → /sourceatlas:flow "[エントリーポイント]"
• リファクタリングが必要 → /sourceatlas:pattern "[パターン]"

→ reference.md#handoffs を参照

code-maat インストール

• デフォルト位置: ~/.sourceatlas/bin/code-maat-1.0.4-standalone.jar
• 自動インストール: ./scripts/install-codemaat.sh
• 必須: Java 8+

→ reference.md#code-maat-installation を参照

解釈ガイドライン

• ホットスポット: 常に悪いとは限らない (コアロジックはよく変わる)
• 結合度: 予期されるもの (同じドメイン) vs 疑わしいもの (クロスモジュール)
• コントリビューター: 健全 = モジュールあたり2～3人、リスク = 単一コントリビューター

→ reference.md#interpretation-guidelines を参照

---

サポートファイル

詳細ドキュメントは以下で利用可能です:

• workflow.md - 完全なステップ0～5実行ガイド (bash コマンド付き)
• output-template.md - 完全な Markdown 構造と例
• verification-guide.md - 自己検証ステップ V1-V4
• reference.md - キャッシュ、code-maat、解釈、トラブルシューティング

---

出力ヘッダー

出力を以下で開始します:

🗺️ SourceAtlas: History
───────────────────────────────
📜 [リポジトリ名] │ [N] ヶ月

その後、output-template.md の完全な構造に従います。