仕様書駆動とメルカリのAnalytics Design Docs

こんにちは、Product Growth Analyticsチームのじゃっこです。最近までメルカリShopsや配送関連の意思決定支援に携わっていましたが、直近は分析チームでのLLM活用に取り組んでおります。

2025年7月、AmazonがAIコーディングツール「Kiro」をリリースして以来、エンジニアリングの世界では「仕様書駆動開発（Spec-Driven Development）」というアプローチが注目を集めています。Kiroは、AIにコーディングをさせる前に、まず要件定義・設計・実装計画を文書化する仕組みを特徴としています。

実は、メルカリには2023年から「Analytics Design Docs（ADD）」という独自の分析設計フレームワークがあり、日々の業務で活用してきました。最近では、このADDをAIにレビューさせる試みも増えています。

この記事では、まず近年のデータ分析と生成AIを取り巻くトレンドを整理した上で、メルカリにおけるADDを主体とした「仕様書駆動データ分析」の実践をご紹介します。

前提知識：データ分析や生成AIを取り巻く最新トレンド

1. 「vibe coding（雰囲気コーディング）」から「仕様書駆動開発」へ

仕様書駆動開発が注目される背景には、「vibe coding（雰囲気コーディング）」という概念の流行があります。これは2025年2月にKarpathy氏が提唱したもので、AIの支援によって非エンジニアでも「雰囲気」で素早く試作品を作れるようになった状況を指します。しかしその一方で、指示が曖昧なために品質や保守性のコントロールが難しいという課題も浮き彫りになりました。

そこで生まれたのが、仕様書駆動のアプローチです。まず「何を作るか」を定義する要件定義書（requirements.md）、「どのように作るか」を記した技術設計書（design.md）、そして「誰がいつ何を実装するか」を整理した実装計画（tasks.md）といった設計書を先に作成します。これにより、LLMの自由度を“有益に制約”し、人間がガバナンスを取り戻すのです。
この考え方は、vibe codingの課題に対する的確な解決策として多くのエンジニアの共感を呼び、Kiro以外のツールでも同様の実装を目指す動きが広がっています。

2. 「プロンプトエンジニアリング」から「コンテキストエンジニアリング」へ

AIエージェントが普及し、複数のステップや長い対話を通じてタスクを実行する時代になると、従来の「1回の命令をどう工夫するか」というプロンプトエンジニアリングだけでは不十分になってきました。

そこで2025年6月頃に登場したのが、「コンテキストエンジニアリング」という新しい概念です。これもvibe codingと同じくKarpathy氏が発信源であり、彼はこれを「コンテキストウインドウにちょうど適切な情報を詰め込む、繊細な芸術であり科学だ」と表現しています。つまり、複雑なワークフローをLLMに実行させるためには、各ステップでLLMが扱いやすいサイズに情報を整理・圧縮して渡すことが重要だということです。

この観点から見ると、段階的に要件や設計を積み上げていく仕様書駆動開発は、コンテキストエンジニアリングの優れた実践例そのものと言えるでしょう。段階化は、長文入力によるコンテキスト肥大化の悪影響を抑制する効果も期待できます。

3. データエンジニアリング領域におけるLLM活用の広がり

データエンジニアリングの分野でも、LLMの活用はコード生成の支援を越えて進化しています。メルカリでもSQL作成はもちろん、Lookerやdbtといったデータ基盤のコード生成に、Cursorを中心としてLLMを活用しています。また一般的に、RAG（Retrieval-Augmented Generation）を用いて社内ドキュメントを検索させるなど、より高度なコンテキスト管理も模索されています。

ただし、これらの知見は主に基盤を構築・運用するデータエンジニア向けに蓄積されています。アナリストが日常の分析業務で、アウトプットの質を高めるためにコンテキストをどう取り込むべきかについては、まだ現場の知見が十分に共有されていません。この点は、今後の大きな議論のポイントだと考えています。

メルカリの「Analytics Design Docs」による分析品質の標準化

ここからは、メルカリが2023年から運用しているAnalytics Design Docs（ADD）についてご紹介します。ADDは、分析プロセスを構造化し、レビューを通じて品質を高めるためのテンプレートです。具体的には、以下の項目とチェックポイントで構成されています。

私も中途採用のため、メルカリのデータ分析に慣れなかった間は、このADDに何度も助けられました。特に、ステークホルダーとの間で背景や前提の認識を揃えきらないまま分析を進めてしまい、ズレたアウトプットを提出して、手戻りを発生させてしまう癖があったのです。ADDに沿って、手を動かす前に分析設計を徹底的に磨き込むことで、手戻りを大幅に減らすことができました。

メルカリの「仕様書駆動データ分析」フレームワーク

ここからは、仕様書駆動とコンテキストエンジニアリングの考え方を、メルカリのADDに統合した具体的なフレームワークをご紹介します。巻末にもCursor Rulesとしてまとめてあります。

データ分析の特性に対応したドキュメント構成

ソフトウェア開発における仕様書駆動は、主にrequirement, design, taskの3つのドキュメントで構成されます。私たちのフレームワークでは、データ分析の特性に合わせてインプット(note)とアウトプット(result, report)を追加しています。

これはデータ分析が、下記の点でプロダクト実装と性質が異なることに対応しています。

• (0)背景・前提によって、正解とされるアウトプットが変わる

• (4)コードとして正しく動くかだけではなく、アウトプットが仮説に応えているかも検証する必要がある

• (5)仮説検証のPDCAを順番に回してアウトプットを生成した後に、ステークホルダーにとってわかりやすいように、内容を取捨選択したり順番を並べ直したりする必要がある

データ分析におけるコンテキストエンジニアリングの要点

LLMの能力を最大限に引き出しつつ、その振る舞いを制御するため、ワークフローとコンテキストの両面からガードレールを設けています。

1. ワークフローの制御

各ドキュメントを段階的に作成し、必ず人間のレビューを挟む「Human in the Loop」を徹底しています。この逐次的なアプローチにより、コンテキストのズレやLLMの暴走を最小限に抑えます。

また、分析の途中で新たな発見があった場合に、前のステップに戻って仮説を修正できる柔軟な再ループの仕組みも取り入れています。

1. コンテキストの制御

分析設計/報告の段階では、メルカリで実績のあるADDのチェックポイントをテンプレートに組み込み、AIが生成するドキュメントの品質を担保しています。

次に分析設計からBigQueryのクエリに落とし込む段階では、ディメンショナル・モデリングの概念を用いて中間テーブルを設計し、LLMへの指示を明確化しています。分析の粒度となる「ディメンション」、測定したい指標である「メジャー」、分析対象を絞り込む「フィルター」を明示することで、LLMに過不足なく仕様を伝えています。(用語はLookerのものをお借りしています。)

dbtやLookerのようなセマンティックレイヤーが整備されていれば、この設計はさらにシンプルになります。メルカリではAIエージェント・Socratesがデータの場所や扱い方の情報を持っているため、この段階だけSocratesで実行することもあります。Socratesについての詳細は下記の対談をご覧ください。

「仕様書駆動」をガードレールに、あくまで走り切るのはアナリスト

多くの方が既に体験されているように、データ分析のプロセスをLLMの自走のみで完結させるのは非常に困難です。なぜなら、データ分析のアウトプットの価値は、コードが正しく動くかだけでなく、その結果がビジネス上の文脈（コンテキスト）において持つ意味によって決まるからです。

今回ご紹介したフレームワークも、各段階で必ず人間がレビューし、軌道修正を行う、Human-in-the-Loopを前提としています(その点では、Claude CodeのようなCLIよりも、CursorなどのIDEの方がお勧めです。)

それでも、このガードレールがあることは、特に(その会社・領域での)経験の浅いデータアナリストにとって大きな助けとなります。これまで人力で作成・レビューしていた分析設計を、AIの支援によって手軽に作成し、フィードバックを得られるようになったことも、アナリストの生産性を大きく向上させるはずです。

このような分析設計におけるLLM活用は、コンテキストエンジニアリングの一分野ですが、データエンジニアリング領域に比べ、アナリストの現場での実践知はまだ不足しています。この記事が、業界全体の議論を活性化させる一助となれば幸いです。

本記事でご紹介したような取り組みに関心をお持ちいただけた方は、ぜひ採用ページもあわせてご覧ください。

補足: Cursor Rules テンプレート

このRulesは骨子のみ抜粋したものです。ご利用の際にはご自身の環境に合わせてカスタマイズしてみてください。Cursor以外のClaude Codeなどでもお試しになれると思います。

# 仕様書駆動データ分析 - Cursor Rules

## 基本ワークフロー
不可逆・Human-in-the-Loopで：
`note.md` → `requirement.md` → `design.md` → `task.md` → `result.md` → `report.md`
※ `result.md`レビュー後に必要なら`requirement.md`へ再ループ

## ワークフロー制御
- 各段階は順序通りに完了後に次へ。**同時作成は禁止**
- 各段階で**人間のレビューを必須化**
- 前段階までの成果物を抜けもれなく反映させること
- `result.md`確認後に仮説修正が必要な場合は、`requirement.md`から再ループ可能

## ドキュメント仕様

### 1.`note.md`（背景情報の記録）
- 議事録・Slack・既存分析リンクを集約
- 可能なら**MCP**でソースを取得

### 2.`requirement.md`（要件定義・分析設計）
- 下記のテンプレート・チェックポイントを遵守
```markdown
1. 背景・前提
- 意思決定者、前提理解度、必要な意思決定・判断
- 過去行われた同様の分析、参考事例
2. 課題・ゴール
- 答えが出ることで打ち手(事業・顧客課題解決)に繋がるか？
3. 仮説
- 答えが分からない状態でも、課題に対する答えのストリートラインを先に言語化し、検証項目を明確にす
4. 分析設計
- 事業・顧客課題を分析課題（分析可能な粒度）に分解することが出来ているか？
- 分析で答えを出す(=分析設計に落とし込む)ことが可能か？
- 分析結果から、課題・仮説に答えを出すことが可能か？
```

### 3.`design.md`（技術設計）
- 分析用中間テーブルの設計
- 下記のテンプレートを遵守
```markdown
- ディメンション（分析の粒度）
  - 例)
    - お客さま: ユーザーID、デモグラ、特定の機能・施策の利用有無
    - 期間: 特定の機能・施策のリリース前後
  - 使用するテーブル・カラム
- メジャー（測定するKPI）
  - 例)
    - 出品や購入の回数・金額
    - 特例の機能・施策の利用回数
  - 使用するテーブル・カラム
- フィルター（分析の対象）
  - 例)
    - お客さま: デモグラ、特定の機能・施策の利用有無
    - 期間: 特定の機能・施策のリリース前後nヶ月
  - 使用するカラムに対する条件
```

### 4.`task.md`（実装計画）
- Phase 1: 分析テーブル作成・検証
- Phase 2: 可視化設計・実装（EDA + 仮説検証）
- 権限エラーや仕様の解釈ミスが発生した場合は、修正内容を`design.md`に反映
- 過去の類似分析を参考にした可視化方法を提案

### 5.`result(.md)`（分析結果）
- Jupyter/Quarto/Marimo等のNotebook形式（ユーザー選択）
- EDAと仮説検証の可視化を含む
- 統計的検証結果、仮説の検証結果、次のアクション
- 下記のチェックポイントを遵守
  - 課題や、分析課題の各問に直接的に回答出来ているか？結論に至っているか？
  - 分析結果をもとに行動改善に繋がるか？

### 6.`report.md`（最終レポート）
- ステークホルダー向けの最終成果物
- `requirement.md`、`design.md`、`task.md`、`result(.md)`の内容を統合
- 下記の構成を遵守
```markdown
## 概要
- 下記の内容を2-3行で要約
## 前提の確認
- `requirement.md`から、ステークホルダー間で揃えておくべき認識を復習
## 分析結果
- `result(.md)`の内容を、データ分析やプロダクトの仕様に詳しくないステークホルダーにもわかるように、取捨選択・並び替える
## 示唆・ネクストステップ
- `result(.md)`の内容をもとに、示唆・ネクストステップを記載
```

Cursorで言うと、Rulesよりも、直近ベータ版がリリースされたCommandの方が相性が良いかもしれません。併せてご検証ください。