前に、CodatumというBIツールについての記事を書きましたが、最近は手元のClaude Codeを分析エージェントとしてそれ以上に愛用しています。
分析をしていると、地味に積み重なるストレス (手間) がいくつかあります。
- 「いつ、どのノートブックで、どんな条件で分析したか」を忘れる
- 類似したクエリを書くたびに過去ファイルを掘り返す
- BIツールのチャート描写力の限界。「この軸を対数スケールにして平均線を重ねたい」「ここにテキストを入れたい」といった細かい要望がツールの能力に制約をうける。ポチポチUIを操作するのも面倒
- 分析Aの結果を受けて分析Bへ、分析Bから分析Cへと深堀り連鎖していくなかで、その過程の仮説や考えを書き留めておくのが面倒で、後からルートを辿れるように構造化していく手間がある
- 示唆をレポートにまとめる際のツール移動。クエリ・チャート・テーブル・インサイトなどのアセットを移動するのが面倒
このあたりのストレスはCodatumでもいくつか残課題として残っていたため、一気通貫に解決するために、Claude Codeでオレオレ環境を構築しています。
実際に運用している分析リポジトリを例に、各工夫を紹介します。
リポジトリの構成
分析リポジトリは、プロダクトをまたいでアセットを使い回せる構成にしています。
.claude/commands/ スキル（全プロダクト共通）
analysis.md
retrospect.md
notion-export.md
lib/ 共通ライブラリ（chart.py など）
products/ プロダクト別アセット
{product-a}/
CLAUDE.md BQプロジェクト設定
context/ ドメイン知識（business.md / metrics.md）
queries/ 人がレビュー済みのSQLテンプレート
schema/ テーブルスキーマ定義
reports/ 各分析セッション
_template/
YYYY-MM-DD_TOPIC/
CLAUDE.md
queries/
report.ipynb
output/
{product-b}/ （同構造・別BQプロジェクト）
.claude/commands/ の3つのスキルは、どのプロダクトの分析にも使えるように汎用化されています。/analysis {product-a} と呼べば一方のプロダクトの分析環境が立ち上がり、/analysis {product-b} と呼べば別プロダクトの環境に切り替わります。context/・queries/・schema/・reports/ はプロダクトごとに独立しており、知識・クエリ・スキーマが混在しません。
lib/ の chart.py はどのプロダクトの分析でも使える共通の可視化ヘルパーで、日本語フォントや配色がすでに設定されています。
Skillsで分析を自動化し、フィードバックを貯める
このリポジトリで設定している頻出スキルは以下のような感じです。
/analysis
分析セッションの立ち上げをまとめたスキルです。データ品質チェック、新規フォルダ作成、過去の関連セッションの提示、queries/にある利用可能なベースクエリの表示、BigQueryのスキーマ取得、そしてクエリを別エージェントが独立検証するQAステップまで、8段階を自動で進めます。「/analysis」と伝えた後、私がやることはセッションの目的を書くことだけです。
/notion-export
分析が完了したら、/notion-exportでレポートをNotionに書き出します。products/{product-a}/CLAUDE.mdに設定されたプロダクトタグとドキュメントタグを読み取り、lib/notion_export.pyを呼び出してNotionのデータベースにページを自動作成します。jupyter nbconvertでHTML化してから投稿する一連の処理がスキル一発で完結するため、ツールを切り替える手間が完全になくなります。
/retrospect
分析が完了したあとに呼ぶと、Claudeが今回の発見を以下の4つのカテゴリに分類して提示するスキルです。
- ビジネス知識（トラップ・データの特性）→
products/{product-a}/context/business.md - 指標・計算ロジック →
products/{product-a}/context/metrics.md - 再利用可能なSQL →
products/{product-a}/queries/*.sqlとして保存 - ワークフロー改善 →
.claude/commands/analysis.mdに反映
各項目についてClaudeに選択肢式Q&Aを提示してもらっているので、「反映する・修正して反映・カテゴリ変更・スキップ」を選ぶだけです。
「この除外条件は毎回必要だ」と気づいたら、次回からdata_quality_check.sqlに自動で含まれます。分析するたびにClaude Codeが賢くなるサイクルが組み込まれています。
以降のセクションでは、各ディレクトリとスキルが実際に何をしているかに触れます。
分析履歴はCLAUDE.mdに積み上げる
「どのセッションで何を調べて、どんな除外条件を設けたか」、これが一番忘れやすい情報です。このリポジトリではreports/YYYY-MM-DD_TOPIC/CLAUDE.mdを分析ごとに作成し、目的・使用テーブル・発見・メモを随時更新するルールにしています。Claude Codeはセッション開始時にこのファイルを読み込み、前回の文脈から即座に再開できます。「あの分析のデータ品質除外条件はどこに書いた？」という忘れ物がゼロになります。
人がレビュー済みのクエリをqueries/に蓄積する
毎回クエリをゼロから書く非効率は、products/{product-a}/queries/ディレクトリで解消しています。ここにはbase_data.sql（全分析の出発点となるマスタークエリ）やstockout_avoid_rate.sql（欠品回避率の計算ロジック）など、人がレビューして精度と汎用性を確認したSQLテンプレートを蓄積しています。products/{product-a}/CLAUDE.mdに「分析の出発点としてqueries/*.sqlを参照すること」と明示することで、Claude Codeは指示なしにこれらを参照・流用するようになります。またdata_quality_check.sqlを「欠品回避率分析の前に必ず実行する」とルール化しており、データ品質の担保も自動化されています。
チャートはコードで書く
BIツールのドラッグ&ドロップには表現の限界があります。このリポジトリではlib/chart.pyという共通可視化ヘルパーを用意し、日本語フォントやスタイルを統一したうえでClaudeにPythonコードを書かせています。「このチャートに平均線を追加して、X軸を月次にして」を自然言語で伝えるだけで、BIツールのUIでは実現しにくい表現が即座にコードになります。
深掘りの連鎖はseries CLAUDE.mdで管理する
「分析A→B→Cと深掘りしたが、なぜBに進んだか後から辿れない」という問題は、シリーズ単位のCLAUDE.mdで解決しています。たとえば「庄内-欠品回避率」というシリーズには4本のサブ分析がありますが、親ディレクトリのCLAUDE.mdに「なぜサブ分析が必要になったか」「共通フィルター」「主要発見のエグゼクティブサマリー」を集約しています。数週間後に見返しても、どういう仮説の流れでCに至ったかが一本の文書で追えます。
深掘りのたびにサブディレクトリが増えていく構造も気に入っています。01_全体概況/、02_デイリー割引除外/、03_ヨーグルト麺SKU/のように、各ステップが独立したフォルダとして残ります。「あの時なぜヨーグルト麺に絞ったのか」を知りたければ03_フォルダのCLAUDE.mdを開けばよく、分析のルートがディレクトリツリーとして可視化されています。
ノートブックでクエリ・チャート・示唆を一元管理する
「SQLを実行した結果をBIツールに持っていき、チャートを作ってドキュメントに貼る」、この3ステップのツール移動がJupyter Notebookで完全になくなりました。report.ipynbにはSQLクエリのコード・実行結果のチャート・分析ナラティブが一体化して存在します。「このチャートのもとになったクエリはどこか」を探し回る必要がなく、ノートブック一本が分析アセットのすべてを内包しています。jupyter nbconvertでHTML化してNotionにエクスポートする仕組みもコマンド化しており、共有コストもほぼゼロです。
新しい分析はこう進む
ここまで紹介した工夫が実際にどう機能するか、具体的な一例で見てみます。
「店舗Aの欠品が先月より悪化している。原因を調べたい」という問いがあったとしたら、/analysis を呼ぶだけでこの流れが完結し、チームにもNotionで共有が簡単にできます。
これまで自分が行ってきた分析業務の大半を自律するエージェントに安心して託すことができるようになったので、最近ではむしろ分析量が増えています。
