Claude Code × Notion MCP で要件定義→コード生成を一気通貫させるワークフロー設計パターン

Posted at 2026-04-06

結論: Notionに要件を書くだけで、設計・実装・テストまで自動化できる

Notionに要件を書いたら、Claude Codeが設計書もコードもテストも全部やってくれる世界線——MCPサーバー1つで実現できます。

本記事で紹介するのは、Notion上の要件定義DBをMCPサーバー経由でClaude Codeに接続し、要件取得→設計書生成→コード実装→テスト作成を一気通貫で回すワークフロー設計パターンです。

この仕組みにより、以下が実現します。

要件の「書き場所」と「読み手（AI）」が直結し、伝言ゲームが消える
Claude Codeがプロジェクトコンテキストを自動で理解し、精度の高いコードを生成する
要件変更時もNotionを更新するだけで、再生成のループが回る

環境・前提条件

項目	バージョン / 要件
Claude Code	最新版（CLI）
Node.js	v18以上
Docker	24.0以上（Docker構成を使う場合）
Notionアカウント	ワークスペース管理者権限
Notion APIインテグレーション	作成済み（Internal Integration）

1. なぜNotion × Claude Codeなのか — ドキュメント駆動開発とAIエージェントの相性

ドキュメント駆動開発の課題

多くのチームが「ドキュメントを書いても、実装時には読まれない」という問題を抱えています。要件定義書がConfluenceやNotionに眠り、実装者はSlackで断片的に仕様を確認する——このドキュメントと実装の断絶がバグや手戻りを生みます。

Claude Codeが変えるゲーム

Claude Codeはファイルシステムを直接操作できるAIエージェントです。しかし、その能力を最大化するには良質なコンテキスト供給が必要です。ここで鍵になるのがMCP（Model Context Protocol）です。

MCPサーバーを介してNotionのデータベースに接続すれば、Claude Codeは以下を「自分で取りに行ける」ようになります。

要件定義の一覧と詳細
優先度・ステータス・担当者情報
受け入れ条件やUI仕様のメモ

つまり、Notionが「要件のSingle Source of Truth」、Claude Codeが「実装エージェント」、MCPが両者をつなぐ「神経系」として機能する構成です。

2. Notion MCPサーバーの構築手順

事前準備: Notion APIインテグレーションの作成

Notion Developers にアクセス
「New integration」でInternal Integrationを作成
必要なCapabilities: Read content, Update content, Insert content
対象のNotionページ/データベースでインテグレーションを「接続」する

取得したInternal Integration Secret（ntn_で始まる文字列）を控えておきます。

パターンA: npxでサクッと起動

最も手軽な方法です。Claude Codeの設定ファイルに直接記述します。

プロジェクトルートの .mcp.json を作成します。

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_xxxxxxxxxxxxx\",\"Notion-Version\":\"2022-06-28\"}"
      }
    }
  }
}

注意: ntn_xxxxxxxxxxxxx の部分は実際のIntegration Secretに置き換えてください。シークレットをリポジトリにコミットしないよう、.mcp.json を .gitignore に追加することを強く推奨します。

パターンB: Dockerで安定運用

チーム開発や永続運用にはDocker構成が適しています。

FROM node:18-slim
WORKDIR /app
RUN npm install -g @notionhq/notion-mcp-server
EXPOSE 3000
CMD ["notion-mcp-server", "--port", "3000"]

# docker-compose.yml
services:
  notion-mcp:
    build: .
    environment:
      - OPENAPI_MCP_HEADERS={"Authorization":"Bearer ${NOTION_API_KEY}","Notion-Version":"2022-06-28"}
    ports:
      - "3000:3000"
    restart: unless-stopped

# .envファイルでシークレットを管理
NOTION_API_KEY=ntn_xxxxxxxxxxxxx

Docker構成の場合、.mcp.jsonはURLベースの接続設定に変更します。

動作確認

Claude Codeを起動して /mcp コマンドで確認します。

claude
# Claude Code内で
/mcp

notion サーバーが「connected」と表示されれば成功です。Notion MCPサーバーが提供する主なツールには、notion_search、notion_retrieve_page、notion_query_database などがあります。

3. ワークフロー設計: Notionの要件DBからCLAUDE.mdを自動生成する仕組み

Notion側のDB設計

要件定義データベースは以下のプロパティで設計します。

プロパティ名	型	用途
Title	タイトル	要件名
Status	セレクト	`Draft` / `Ready` / `In Progress` / `Done`
Priority	セレクト	`P0` / `P1` / `P2`
Category	セレクト	`Feature` / `Bug` / `Refactor`
Acceptance Criteria	リッチテキスト	受け入れ条件
Tech Notes	リッチテキスト	技術メモ・制約事項
Assigned Sprint	セレクト	対象スプリント

ポイント: StatusがReadyのものだけをClaude Codeが取得するようにフィルタリング設計します。

CLAUDE.mdの自動生成パターン

CLAUDE.mdはClaude Codeがプロジェクトコンテキストを理解するための設定ファイルです。以下のワークフローで、Notionの要件をCLAUDE.mdに反映させます。

具体的なプロンプト例を示します。

Notionの要件定義DBから、Statusが"Ready"の要件をすべて取得してください。
取得した要件をもとに、以下を実行してください：

1. CLAUDE.md を更新（プロジェクト概要、技術スタック、コーディング規約を含む）
2. docs/requirements.md に要件一覧を構造化して出力
3. 各要件の受け入れ条件からテスト方針を docs/test-strategy.md に出力

CLAUDE.mdのテンプレート構造

生成されるCLAUDE.mdの理想的な構造はこのようになります。

# プロジェクト概要
{Notionの要件サマリから自動生成}

# 技術スタック
- フロントエンド: React + TypeScript
- バックエンド: Node.js + Express
- DB: PostgreSQL

# 現在のスプリント要件
## P0（必須）
- [ ] {要件タイトル}: {概要}
## P1（重要）
- [ ] {要件タイトル}: {概要}

# コーディング規約
- テストは各機能に対してunitテストを必須とする
- 受け入れ条件はNotionの記載に準拠する

# 受け入れ条件一覧
{Notionから取得したAcceptance Criteriaを一覧化}

4. 実演: ToDoアプリの要件→設計→実装→テストを一気通貫で回す

ここからは具体例として、シンプルなToDoアプリを題材に一気通貫ワークフローを回します。

Step 1: Notionに要件を登録

Notion DBに以下の3つの要件をStatus: Readyで登録します。

Title	Priority	Acceptance Criteria
タスク一覧表示	P0	GET /api/todos で全タスクがJSON配列で返る
タスク追加	P0	POST /api/todos でタスクが作成され、201が返る
タスク完了切替	P1	PATCH /api/todos/:id で completed が反転する

Step 2: Claude Codeに指示

claude

Notionの要件データベースを検索して、Status が Ready の要件をすべて取得してください。
その要件をもとに、Node.js + Express + TypeScript で REST API を実装してください。

以下の手順で進めてください：
1. 要件をNotionから取得して確認
2. CLAUDE.md を生成
3. プロジェクト初期化（package.json, tsconfig.json）
4. APIの実装（src/配下）
5. 各要件の受け入れ条件に基づくテスト作成（Jest）
6. すべてのテストが通ることを確認

Step 3: Claude Codeの実行フロー

Claude Codeは以下を自律的に実行します。

実際に生成されるコードの例

Claude Codeが生成する src/routes/todos.ts の一例です。

import { Router, Request, Response } from 'express';

interface Todo {
  id: string;
  title: string;
  completed: boolean;
  createdAt: Date;
}

const todos: Todo[] = [];
const router = Router();

// GET /api/todos - タスク一覧表示（Notion要件: P0）
router.get('/', (_req: Request, res: Response) => {
  res.json(todos);
});

// POST /api/todos - タスク追加（Notion要件: P0）
router.post('/', (req: Request, res: Response) => {
  const todo: Todo = {
    id: crypto.randomUUID(),
    title: req.body.title,
    completed: false,
    createdAt: new Date(),
  };
  todos.push(todo);
  res.status(201).json(todo);
});

// PATCH /api/todos/:id - タスク完了切替（Notion要件: P1）
router.patch('/:id', (req: Request, res: Response) => {
  const todo = todos.find(t => t.id === req.params.id);
  if (!todo) return res.status(404).json({ error: 'Not found' });
  todo.completed = !todo.completed;
  res.json(todo);
});

export default router;

Notionの受け入れ条件がそのままAPIの仕様に反映されている点に注目してください。

Step 4: Notionのステータスを更新

実装完了後、Claude Codeに「Notionの各要件のStatusをDoneに更新して」と指示すれば、MCPサーバー経由でNotionのDBも更新されます。これで要件管理と実装のループが閉じます。

5. ハマりポイント3選

🔥 ハマりポイント①: トークン爆発

問題: Notionのページにリッチコンテンツ（画像、埋め込み、長文）が大量にあると、MCPサーバーが返すデータが膨大になり、Claude Codeのコンテキストウィンドウを圧迫します。

対策:

要件DBのプロパティはテキストベースで簡潔に書く
詳細仕様は別ページにリンクし、必要な場合だけ個別取得する
notion_query_database のフィルタを活用し、取得件数を絞る
1回のプロンプトで全要件を取得せず、Priority別に分割取得する

🔥 ハマりポイント②: 権限スコープの罠

問題: Notion APIのインテグレーションは、明示的に「接続」されたページ/DBしかアクセスできない。「なぜかデータが取得できない」場合、大抵これが原因です。

対策:

対象のデータベースを開き、右上の「...」→「接続」→ 作成したインテグレーションを追加
子ページには権限が自動継承されるが、リンクされた別DBには継承されないことに注意
インテグレーションのCapabilitiesで「Read content」が有効になっているか確認

🔥 ハマりポイント③: DB構造の設計ミス

問題: Notionのプロパティ名に日本語や特殊文字を使うと、MCPサーバー経由で取得したJSONのパースで予期しない挙動が起きることがあると言われています。

対策:

プロパティ名は英語のスネークケースまたはキャメルケースで統一する
セレクトの選択肢も英語で管理する（表示名だけ日本語にする運用でもOK）
リレーションやロールアップは構造が複雑になるため、最初はシンプルなプロパティだけで始める

6. プロジェクト規模別おすすめ構成

個人開発（1人）

Notion Free Plan + npx起動 + CLAUDE.md手動更新

.mcp.jsonに直書きでOK
要件DBは1つのシンプルなテーブル
CLAUDE.mdの更新は「Notionから取得して更新して」の一言プロンプト
コスト: ほぼゼロ

チーム開発（3〜10人）

Notion Team Plan + Docker MCP + CLAUDE.md自動生成スクリプト + GitHub Actions連携

MCPサーバーはDockerで常時起動、チーム共有
Notionの要件DBに「Assigned To」プロパティを追加し、担当者別にフィルタ
CI/CDパイプラインでNotion→CLAUDE.md生成を自動化
.mcp.jsonのシークレットは環境変数で管理

大規模開発（10人以上）

Notion Enterprise + 複数MCP Server + マイクロサービス別DB + ガバナンス層

サービスごとにNotionのDBを分離
MCPサーバーもサービスごとに分離し、アクセス範囲を制御
要件→設計→実装の各フェーズでレビュープロセスを挟む
Claude Codeの実行ログを監査用に保存

まとめ

Notion MCPサーバーを導入するだけで、Claude CodeがNotionの要件を直接読み書きできるようになり、「要件定義→コード生成」の一気通貫ワークフローが実現する
CLAUDE.mdをNotionの要件DBから自動生成する仕組みを作ることで、AIエージェントに常に最新のプロジェクトコンテキストを供給でき、コード生成の精度が飛躍的に上がる
トークン爆発・権限スコープ・DB設計の3つのハマりポイントを事前に押さえておけば、個人開発からチーム開発まで段階的にスケールさせられる

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up