alive-analysis

alive-analysis

AI コーディングエージェント向けの構造化分析ワークフロー — すべての分析を追跡可能、再現可能にし、チームで共有できます。

---

なぜこれが必要なのか

Claude に指標の低下を調査するよう頼むと、答えが返ってきます。そして、その答えに基づいて行動します。

3 か月後、「なぜあれを変更したんだっけ？」——記録はありません。推論も、データの確認も、監査証跡もありません。

あるいは、新しいチャットを開き、すでに行った作業を繰り返しながら、背景を最初からすべて説明し直します。

alive-analysis は、すべての分析を構造化されたバージョン管理可能なワークフローにすることで、この問題を解決します。 Claude が 5 段階のループを案内します。各段階で Markdown ファイルが作成されます。すべてがリポジトリに保存され、あなたも Claude も検索できます。

その結果、チームが何を決めたかだけでなく、どのように考えるかについてのナレッジベースが成長していきます。

---

仕組み

You describe a question  →  /analysis-new
                                 ↓
         Claude walks you through 5 stages:
         ASK → LOOK → INVESTIGATE → VOICE → EVOLVE
                                 ↓
              Each stage = one markdown file in analyses/
                                 ↓
         Files are Git-tracked, full-text searchable,
         readable by Claude in future conversations
                                 ↓
         Six months later: /analysis-search "checkout drop"
         → Claude surfaces context, findings, and follow-ups

---

インストール

# Clone the repo
git clone https://github.com/with-geun/alive-analysis.git /tmp/alive-analysis

# Install — pick your platform
bash /tmp/alive-analysis/install.sh              # Claude Code
bash /tmp/alive-analysis/install.sh --cursor     # Cursor
bash /tmp/alive-analysis/install.sh --both       # Both

# One-time setup — run in your AI agent chat (not the terminal)
/analysis-init    # Configure language, team, data stack, key metrics
/analysis-new     # Start your first analysis

これだけです。あとは Claude が対応します。

---

ALIVE ループ

すべての分析は、同じ 5 段階の構造に従います。各段階には明確な目的、チェックリスト、そして次の段階に進む前の品質ゲートがあります。

段階	問い	成果物
❓ ASK（問う）	何を知りたいのか、そしてなぜか？	仮説ツリー、範囲、成功基準
👀 LOOK（見る）	データには実際に何が示されているのか？	データ品質の評価、SQL テンプレート
🔍 INVESTIGATE（調査する）	本当の原因は何か？	信頼度付きの調査結果
📢 VOICE（伝える）	つまり何が言えて、次に何をすべきか？	推奨事項、対象者に合わせたメッセージ
🌱 EVOLVE（発展させる）	何が変われば結論も変わるのか？	フォローアップ分析、影響の追跡

意図的に選択しない限り、段階を飛ばすことはありません。このループによって、急いでいるときでも分析上の規律が保たれます。

---

3 つのモード

Full Mode — 重要な意思決定向け

段階ごとに 1 つ、合計 5 つのファイルを作成します。約 40 項目のチェックリストを備え、すべての専門エージェントを利用できます。重大な意思決定や、推論を説明する必要があるとき、または完全な監査証跡が必要なときに使用してください。

analyses/active/F-2026-0303-001_checkout-drop/
├── 01_ask.md
├── 02_look.md
├── 03_investigate.md
├── 04_voice.md
└── 05_evolve.md

Quick Mode — 迅速な対応向け

すべてを 1 つのファイルにまとめます。簡潔なチェックリストを使用します。ALIVE の構造は同じですが、より軽量です。探索的な質問、朝会、または 1 時間以内に済ませたい分析に使用してください。範囲が広がった場合は、/analysis-promote で自動的に Full に変換できます。

analyses/active/quick_Q-2026-0308-001_dau-check.md

Learn Mode — スキル習得向け

ルーブリックに基づく採点、段階的なヒント、よくある間違いの検出機能を備えたガイド付きシナリオです。2 つのレベルにまたがる、実際の業務を想定した 7 つのシナリオがあります。新しいアナリストのオンボーディング、慣れていない分析タイプの練習、インターンのトレーニングに使用してください。

analyses/active/L-2026-0220-002_signup-drop-scenario/

---

すべてのコマンド

コアワークフロー

コマンド	機能
/analysis-init	初回セットアップ：言語、チーム名、データスタック、主要指標を設定します
/analysis-new	新しい分析を開始します — Full または Quick を選び、質問を設定します
/analysis-next	品質ゲートを確認して、次の ALIVE 段階に進みます
/analysis-status	現在の段階、チェックリストの進捗、未解決の質問を表示します
/analysis-archive	完了としてマークし、analyses/archive/ に移動します
/analysis-list	フィルター（タイプ、段階、分析担当者、タグ）を使ってすべての分析を一覧表示します
/analysis-promote	範囲が広がったときに、Quick 分析を Full にアップグレードします

過去の作業の検索とレビュー

コマンド	説明
/analysis-search	すべての分析を全文検索します。対象はタイトル、調査結果、仮説です
/analysis-retro	期間を指定して振り返りレポートを生成します（--last-month、--last-quarter、--all）
/analysis-dashboard	分析を JSON にエクスポートし、ビジュアルチームダッシュボードに読み込みます
/analysis-dr	意思決定記録（Decision Records）を管理します。チームの方法論に関する意思決定ログです
/analysis-wiki	Analysis Wiki を管理します。すべての分析から AI が編成したナレッジベースです

専門エージェント

コマンド	説明
/analysis-agent	現在の段階に推奨される専門エージェントを表示します
/analysis-agent {number}	特定のエージェントを直接実行します
/analysis-agent "{alias}"	エイリアスで実行します（例："stats"、"causal"、"ethics"）

実験とモニタリング

コマンド	説明
/analysis-new（Experiment type）	A/B テスト分析を開始します。事前登録を含む ALIVE ループを適用します
/monitor-setup	アラートしきい値を設定して、メトリクスのモニタリングを構成します
/analysis-new --from-alert {alert-id}	メトリクスアラートを新しい分析に直接エスカレーションします

教育モード

コマンド	説明
/analysis-learn	学習シナリオを開始します。レベルとシナリオを選択します
/analysis-learn-next	現在の段階についてフィードバックを受け、次に進みます
/analysis-learn-hint	ヒントをリクエストします（3 段階：方向性 → 具体的 → ほぼ答え）
/analysis-learn-review	採点付きレビューとスキルレーダーでシナリオを完了します

---

31 の専門エージェント

各 ALIVE 段階で、ルーティングエンジンが分析コンテキストを読み取り、31 のエージェントから適切な専門エージェントを推奨します。実行するエージェントは自分で選択できます。

必須ゲート（確認不要で自動実行）

次の 4 つは、トリガー条件を満たすと自動的に実行されます。

エージェント	実行条件
scope-guard	複数の質問の混在やスコープの拡大を検出し、範囲を絞るための 3 つの選択肢を提示します
data-quality-sentinel	LOOK を離れる前にデータの完全性を確認します
ethics-guard	PII の露出、生存者バイアス、公平性の問題を検出します
reproducibility-keeper	再現に十分な手順が文書化されているかを検証します

段階ごとの任意の専門エージェント

ASK — problem-framer、hypothesis-gen、metric-translator、sampling-designer

LOOK — data-scout、tracking-auditor、lineage-mapper、sql-writer

INVESTIGATE — eda-agent、stats-agent、experiment-designer、causal-agent、root-cause-analyst、ml-agent、forecast-agent、anomaly-detector、chart-recommender、dashboard-designer、peer-reviewer

VOICE — narrative-agent、exec-summarizer、decision-memo-writer

EVOLVE — metric-definer、semantic-layer-engineer、governance-steward

ルーティングエンジンは、現在のコンテキスト（分析の種類、ドメイン、データの兆候）に基づいて各エージェントを評価し、上位 3 つを平易な説明とともに提示します。「この分析にはランダム化のない前後のメトリクス変化が含まれています。causal-agent が、ここで DID または RDD が適切かどうかを評価できます。」

エージェントは .analysis/agents.yml でプロジェクトごとに無効化できます。

---

実験のサポート（A/B テスト）

/analysis-new を実行して Experiment type を選ぶと、ALIVE ループが次のように適応します。

DESIGN → VALIDATE → ANALYZE → DECIDE → LEARN

主な適用ルール：

• 事前登録ロック：結果を開示する前に分析計画を作成してロックし、事後的な正当化を防ぎます
• SRM の検出：VALIDATE 中にサンプル比率の不一致を自動的に検出します
• ガードレールメトリクス：意図しない副作用を検出できるよう、主要メトリクスと併せて対抗指標を定義します
• 多重比較の補正：補正なしで多数のバリアントを実行した場合に警告します
• 統計的妥当性：有意差を判定する前に、stats-agent が検出力、サンプルサイズ、検定の選択を検証します

---

メトリクスのモニタリング

/monitor-setup

主要なメトリクスにしきい値を設定します。アラートが発生したら、分析へ直接エスカレーションします。

/analysis-new --from-alert {alert-id}

ALIVE のコンテキストには、メトリクス名、値、時間枠、関連セグメントなどのアラートデータが事前入力されます。コンテキストがすでに読み込まれた状態で、ASK から開始できます。

---

分析の検索と振り返り

過去のすべての分析を検索する

/analysis-search "checkout funnel"

タイトル、仮説、調査結果、フォローアップを対象とした全文検索です。周辺のコンテキスト、関連する分析への相互参照、フォローアップ作業の提案とともに、一致した分析を返します。

自動振り返り

/analysis-retro --last-quarter

指定期間内のすべての分析を集約し、構造化されたレポートを生成します：

• 活動の概要（種類別・分析者別の分析件数、ステージの完了状況）
• インパクトの追跡（推奨事項 → 意思決定 → 成果）
• 繰り返し現れるパターンと未解決のフォローアップ
• チームレベルのメトリクス（採用率、意思決定の速さ、時間の経過に伴う分析精度）

出力：analyses/.retro/retro_{period}.md

---

分析メモリシステム（v1.4）

チームに永続的な分析メモリを提供する2つの機能です。知識が蓄積され、チャット履歴の中に消えてしまうことがなくなります。

意思決定記録 — /analysis-dr

ソフトウェアエンジニアリングのアーキテクチャ決定記録（ADR）の概念を応用した、追記専用の方法論に関する意思決定ログです。

解決する課題： チームが2か月前にすでに決めたにもかかわらず、Claude が「ベイズ A/B テストを試してみては？」と提案し続けることがあります。また、新しい分析者が、ほかのメンバーとは異なる DAU の定義を使うこともあります。意思決定記録は、すでに決まったこととその理由を AI に永続的に記録することで、こうした問題を防ぎます。

5つの意思決定タイプ：

タイプ	記録する内容
メトリクス	メトリクスの定義方法（「DAU = アプリの起動ではなく、コア機能の使用」）
方法論	統計手法の選択（「A/B テスト：ベイズ法、信用度95%」）
範囲	セグメントや時間枠の基準（「新規ユーザー = 初回から7日間、D0を含む」）
モデル	アルゴリズムの選択と、代替案を退けた理由
原則	分析基準（「因果関係の主張には DiD/RD/IV が必要」）

追記専用： 意思決定が編集または削除されることはありません。覆された場合、古い DR は Superseded by DR-NNN としてマークされるため、将来の分析者は、当時チームが異なる考え方をしていた理由を理解できます。

/analysis-dr new        # Write a new decision record
/analysis-dr scan       # Find DR candidates from existing analyses
/analysis-dr list       # Show all recorded decisions
/analysis-dr show 003   # Show DR-003 in detail

DR はエージェントシステムと連携します。方法論を提案する6つのエージェント（hypothesis-gen、stats-agent、metric-definer、metric-translator、experiment-designer、causal-agent）は、代替案を提案する前に意思決定記録を確認します。同じ方法論について、何度も議論する必要はありません。

---

分析 Wiki — /analysis-wiki

チームの分析からまとめられた、構造化された AI メンテナンスのナレッジベースです。Andrej Karpathy の LLM Wiki コンセプトに基づいています。毎回生のファイルを検索するのではなく、AI が知識を構造化されたページに事前にまとめ、分析が蓄積されるにつれてページを成長させます。

仕組み： 分析をアーカイブした後、/analysis-wiki update を実行します。AI がアーカイブ済みの分析をすべて読み込み、構造化されたページを作成します。

• analyses/wiki/metrics/dau.md — すべての分析で DAU について判明した内容：重要な知見、検証済み／棄却済みの仮説、注意すべき点
• analyses/wiki/patterns/simpson-paradox.md — 繰り返し現れるパターンと、それらが現れた状況や経緯
• analyses/wiki/hypotheses/INDEX.md — 分析を横断した仮説の結果（すでに回答済みの内容を再検証しないようにします）

健全性チェック： /analysis-wiki check は、矛盾（同じ仮説がある分析では検証され、別の分析では棄却されている場合）、古くなったページ、ソースへのリンクがない孤立した主張を見つけます。

/analysis-wiki update       # Scan archives → build/update all wiki pages
/analysis-wiki check        # Find contradictions, stale content, gaps
/analysis-wiki show dau     # Display the DAU knowledge page

ほかの機能との違い：

機能	使用する場面
/analysis-search	特定の過去の分析を探す
/analysis-retro	ある期間に何が起きたかを要約する
ダッシュボード	分析間の関係を視覚的に確認する
/analysis-wiki	チームが指標やパターンについて学んだことをすべて把握する

DR と Wiki を併用すると、DR は 「これを測定すると決めた経緯は？」 に答え、Wiki は 「測定して何がわかった？」 に答えます。

使い始める：

1. /analysis-init を実行します — 初期データを含む INDEX ファイルとともに、analyses/decisions/ と analyses/wiki/ が作成されます
2. 分析をいくつか実行し、アーカイブします
3. /analysis-dr scan を実行します — AI がアーカイブ済みの分析をスキャンし、記録する手法上の判断を提案します
4. アーカイブが 3 件以上になったら /analysis-wiki update を実行します — AI が指標／パターン／仮説のページをまとめます
5. 定期的に /analysis-wiki check を実行し、矛盾や古くなった知識を見つけます

Quick 分析について： Wiki ページは主に Full 分析（5 段階のファイル）から作成されます。Quick 分析（単一ファイル）は段階ごとに分かれたファイルがないため、Wiki への寄与は少なめです。

---

チームダッシュボード

分析履歴全体を、インタラクティブなノードグラフとして可視化します。

グラフに表示される内容：

• 各ノード = 1 件の分析
• ノードのサイズ = ALIVE のステージの進捗状況（小さい = 開始直後、大きい = 完了）
• ノードの色 = 分析の種類（調査／実験／シミュレーション／学習）
• 円弧のリング = 完了したステージ
• 破線のエッジ = 分析間のフォローアップのつながり
• 実線のエッジ = 同じタグを共有する分析
• ノードをクリック → 関連する分析は強調表示されたままになり、それ以外はすべて薄く表示されます

フィルター： アナリスト、タグ、種類、ステータス、日付範囲。⌘K で検索できます。

セットアップ：

# Export your analyses to JSON
bash dashboard/export.sh > export.json

# Open in any browser — no server needed
open dashboard/alive-dashboard.html
# Click Load → paste the JSON

分析ごとにメタデータを追加して、グラフを充実させます：

# analyses/active/F-2026-0303-001_checkout-drop/meta.yml
analyst: geun
tags: [checkout, conversion]
followups: [F-2026-0305-001]
keyFinding: "2.4pp drop confirmed. Mobile UX root cause."

---

MCP サーバー — Claude が分析を照会できるようにする

MCP サーバーをインストールすると、Claude はあらゆる MCP 互換クライアントから、分析履歴全体に直接アクセスできます。

npm install -g alive-analysis-mcp

Claude Desktop（~/Library/Application\ Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "alive-analysis": {
      "command": "alive-analysis-mcp",
      "args": ["--analyses-dir", "/path/to/your/analyses"]
    }
  }
}

Claude Code（プロジェクト内の .claude/mcp.json）：

{
  "alive-analysis": {
    "command": "alive-analysis-mcp",
    "env": { "ALIVE_ANALYSES_DIR": "./analyses" }
  }
}

MCP を接続すると Claude にできること

ツール	プロンプトの例
alive_list	「前四半期の実験をすべて一覧表示して」
alive_get	「F-2026-0303-001 の調査結果をすべて表示して」
alive_search	「SRM またはサンプル比について言及している分析を探して」
alive_dashboard_export	「ダッシュボードに読み込む JSON を出して」

MCP が有効になると、Claude はセッションをまたいでチームの分析履歴を記憶します。新しいチームメンバーが 「チェックアウトの離脱について何が分かった？」 と尋ねるだけで、誰かがファイルを探し回らなくても、詳しい概要を得られます。

MCP レジストリ： io.github.with-geun/alive-analysis Claude Desktop、Claude Code、Cursor、Zed、Windsurf、およびその他の MCP 対応クライアントで利用できます。

---

教育モード — プロダクト分析を学ぶ

ガイド付きのフィードバックを含む、実際の状況に基づいた 7 つのシナリオです。ツールの操作方法だけでなく、分析的思考を身につけることを目的としています。

初級シナリオ（20～30 分、クイック形式）

シナリオ	質問	練習するスキル
b1-signup-drop	「昨日、登録数が減ったのはなぜ？」	プラットフォーム固有の根本原因、データの突き合わせ
b2-onboarding-comparison	「どちらのオンボーディングフローが優れている？」	シンプソンのパラドックス、SRM の検証、カウンターメトリクス
b3-turnover-cost	「離職によってどれくらいのコストが発生している？」	定量化、複数要素による推定

中級シナリオ（45～60 分、フル形式）

シナリオ	質問	練習するスキル
i1-dau-drop	「DAU が 15％減ったのはなぜ？」	複数の視点からの分析、仮説の除外、確信度の評価
i2-delivery-fee	「配送料を引き下げるべき？」	方針のシミュレーション、感度分析、不確実性の伝達
i3-ab-test-checkout	「新しいチェックアウトでコンバージョン率は改善した？」	実験の妥当性、SRM の検出、ガードレール指標
i4-churn-prediction	「どのユーザーが離脱するか予測できる？」	ML パイプライン、特徴量選択、モデルカード、ドリフト監視

フィードバックの仕組み

各段階で、Claude はルーブリックに照らして作業を評価し、ありきたりな称賛ではなく具体的なフィードバックを返します。行き詰まった場合は、方向性 → 具体的な内容 → ほぼ答え、の 3 段階のヒントを利用できます。よくある間違いをした場合は、なぜ重要なのかという説明とともに指摘されます。

修了までの道のり：初級シナリオを 2 つ、70％以上でクリア → 中級が解放 → 中級で 75％以上を達成 → 本番環境で使えるレベル。

/analysis-learn              # Pick a scenario
/analysis-learn-hint         # Get a hint without giving away the answer
/analysis-learn-review       # See your score and skill radar

---

状況別プロトコル

多くの分析を脱線させる状況に対応する仕組みが、ワークフローに組み込まれています。

スコープ拡大の抑制 — 分析中に 2 つ目の質問が出てくると、エージェントがそれを検出し、後続の課題として保留する、主な質問を入れ替える、トレードオフを文書化したうえで明示的にスコープを広げる、という 3 つの選択肢を提示します。

深掘りの抑制 — サブ質問について 3 回検討した後も、引き続き実行可能かどうかを確認します。実行可能でない場合は、判断が必要なポイントを提示します。

データ品質に関する緊急時対応 — 5 つの対応方法があります。利用可能なデータで補修する、スコープを縮小する、データが整うまで一時停止する、明確な但し書きを付けて報告する、または質問を全面的に見直す方法です。

分析の独立性 — あらかじめ決められた結論に誘導する圧力に対する安全策が組み込まれています。プロンプトのパターンから結論ありきの推論が疑われる場合は、その旨が指摘されます。

---

Obsidian との連携

analyses/ フォルダーは、そのまま Obsidian の保管庫として使えます。

Markdown 内で [[F-2026-0305-001]] の Wiki リンクを使用すると、Obsidian のグラフビューがリンクを認識し、チームのダッシュボードに表示されるものと同じつながりを描画します。コードのワークフローと並行して、ナレッジ管理に Obsidian を使いたいチームに便利です。

---

ファイル構成

your-project/
├── analyses/
│   ├── active/
│   │   ├── F-2026-0303-001_checkout-drop/    # Full analysis
│   │   │   ├── 01_ask.md
│   │   │   ├── 02_look.md
│   │   │   ├── 03_investigate.md
│   │   │   ├── 04_voice.md
│   │   │   ├── 05_evolve.md
│   │   │   ├── meta.yml
│   │   │   └── assets/
│   │   │       └── queries/
│   │   └── quick_Q-2026-0308-001_dau-check.md  # Quick analysis
│   ├── archive/                               # Completed analyses
│   ├── decisions/                             # Analysis Decision Records
│   │   ├── INDEX.md                           # DR index (auto-updated)
│   │   └── DR-NNN.md                          # Individual decision files
│   └── wiki/                                  # AI-maintained knowledge base
│       ├── INDEX.md
│       ├── metrics/                           # One page per metric
│       ├── patterns/                          # Recurring analytical patterns
│       └── hypotheses/                        # Cross-analysis hypothesis results
├── .analysis/
│   ├── config.md          # Team settings (language, data stack, metrics)
│   ├── agents.yml         # Enable/disable individual agents
│   ├── checklists/        # Stage checklists — edit to customize
│   ├── status.md          # Current analysis state
│   ├── agent-state.md     # Agent suppression history
│   ├── models/            # ML model registry
│   ├── metrics/           # Metric definitions and monitors
│   └── decisions/         # Per-analysis business decision memos (VOICE stage output, not DR records)

タイプ別の分析 ID：

• F-YYYY-MMDD-NNN — 調査またはモデリング（フル）
• Q-YYYY-MMDD-NNN — クイックチェック
• E-YYYY-MMDD-NNN — 実験／A/B テスト
• S-YYYY-MMDD-NNN — シミュレーション
• L-YYYY-MMDD-NNN — 学習シナリオ

---

プラットフォームのサポート

機能	Claude Code	Cursor 2.4+
ALIVE ループ全体	✅	✅
25 個以上のコマンドすべて	✅	✅（バッチインタラクション）
31 種類の専門エージェント	✅	✅
教育モード	✅	✅
MCP サーバー	✅	✅
チームダッシュボード	✅	✅
意思決定記録（DR）	✅	✅
分析ウィキ	✅	✅

Cursor はバッチインタラクションモデルを採用しています。入力を順番にではなく、必要なものをすべて一度に提示し、Cursor のエージェントループの動作に合わせて最適化されています。

---

これは何ではないか

BI ツールではありません。 チームダッシュボードで可視化するのは分析履歴であり、ビジネス指標ではありません。alive-analysis が構造化するのは、レポート作成ではなく、思考です。

データパイプラインではありません。 データベースに接続したり、クエリを自動実行したりすることはありません。どのクエリを実行するか、そしてその理由を考えるのに役立ちます。

データスタックに特定の選択を求めません。 SQL、Python、R、ノートブック、スプレッドシートをどのように組み合わせても動作します。この方法論は特定のツールに依存しません。

---

変更履歴の主な内容

バージョン	リリース内容
v1.4.0	分析メモリシステム — 意思決定記録（DR）+ 分析ウィキ（LLM Wiki のコンセプト）
v1.3.0	チームダッシュボード（インタラクティブなノードグラフ）、MCP サーバー（npm + MCP Registry の alive-analysis-mcp）
v1.2.0	31 種類の専門エージェント — レジストリ、ルーター、専用プロンプト 31 個、Cursor のエージェントテーブル全体
v1.1.0	教育モード — 7 つのシナリオ、よくある間違いへのフィードバック、4 つのコマンド × 2 つのプラットフォーム
v1.0.0	分析検索、自動振り返り、README の統合
v0.3.0	A/B テストモジュール、指標モニタリング、Quick から Full への昇格、プラットフォームの分割（Claude Code / Cursor）

変更履歴の全文：CHANGELOG.md

---

コントリビューション

Issue と PR を歓迎します。CONTRIBUTING.md をご覧ください。

ライセンス

MIT — with-geun