記事一覧/連携・プラグイン

⬡ 連携・プラグイン/2026-04-09中級

Antigravity × Notion API連携：ドキュメント駆動開発を自動化するAIワークフロー

AntigravityとNotion APIを連携させ、仕様書からコード・テスト・PR説明文まで自動生成するドキュメント駆動開発（DDD）ワークフローを完全解説。MCPサーバー構築から本番運用まで。

antigravity⁴³⁵ notion api¹³ automation⁵¹ workflow³⁷ mcp¹⁴ documentation⁴

✦ プレミアム記事

取り組みの背景：「仕様書とコードがズレる」問題を根本から解決する

「Notionに仕様書を書いたのに、実装したコードが全然違う方向に進んでいた」「PRレビューで仕様との差異を指摘されるたびに手が止まる」——こうした経験は、多くの開発者にとって日常的な悩みです。

仕様書とコードは本来、常に同期しているべきものです。しかし現実には、開発が進むにつれてこの2つの間にどんどんギャップが生まれてしまいます。その原因は単純で、仕様書を書く作業とコードを書く作業が、ツールレベルで分断されているからです。

ここで扱うのは**Antigravity IDEとNotion APIを連携させたドキュメント駆動開発（Document-Driven Development / DDD）**の実装を完全解説します。Notionの仕様書を直接読み込んでAntigravityがコードを生成し、完成したコードのサマリーを自動でNotionに書き戻す——この双方向ワークフローが実現すると、仕様書とコードの乖離という問題は構造的になくなります。

この記事で構築するシステムの全体像：

Notion → Antigravity: Notion上の仕様書・タスクをMCP経由でAntigravityが読み込み、コード・テスト・PR説明文を生成
Antigravity → Notion: 生成されたコードの実装サマリー・進捗状況をNotionに自動書き戻し
GitHub連携: PRが作成されると仕様書のステータスが自動更新

対象読者は、Notionを日常的に使っていてAntigravityの活用を深めたい中級〜上級の開発者です。

前提環境と準備

必要なもの

Antigravity IDE（最新版）
Notionアカウント（無料プランでも動作）
Node.js 20以上
GitHub CLI（gh）（オプション）

Notion APIの初期設定

まずNotion側でAPIインテグレーションを作成します。

ステップ1: インテグレーション作成

Notion Developers にアクセスし、「New integration」をクリックします。

設定項目：

Name: Antigravity Dev Assistant
Associated workspace: 使用するワークスペースを選択
Capabilities: Read content / Update content / Insert content の3つを有効化

「Submit」をクリックすると、Internal Integration Secret（secret_xxx...形式）が表示されます。これを安全な場所に保存してください。

ステップ2: データベースの準備

Notionに以下の構造を持つデータベースを作成します：

📋 開発タスクDB
├── Name（タイトル）: タスク名
├── Status（セレクト）: Todo / In Progress / Done / Blocked
├── Priority（セレクト）: High / Medium / Low
├── Spec（テキスト）: 仕様詳細
├── Implementation（テキスト）: 実装サマリー（Antigravityが書き込む）
├── PR URL（URL）: 対応するPRのURL
└── Assignee（ユーザー）: 担当者

作成したデータベースのURLからDatabase IDを抽出します：

https://www.notion.so/[workspace]/[DATABASE_ID]?v=xxx

ステップ3: インテグレーションをデータベースに接続

データベースページの右上「...」→「Connections」→先ほど作成したインテグレーションを選択して接続します。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること

✦Notion仕様書を読み込んでAntigravityが自動でコードを生成する仕組みを今日から実装できる

✦MCPサーバー経由でNotionとAntigravityを繋ぎ、コード→PR説明文→Notion更新まで一気通貫で自動化する設計パターンを習得できる

✦ドキュメント駆動開発（DDD）により「仕様とコードのズレ」という慢性的な課題を根本解決し、チームの開発速度を2倍以上に引き上げられる

Stripe による安全な決済 · いつでもキャンセル可能

✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または

メンバーシップなら全記事が読み放題 →

MCPサーバーの構築：Antigravityとの橋渡し

Antigravity IDEはMCP（Model Context Protocol）を通じて外部ツールと連携できます。Notion用のMCPサーバーを構築することで、Antigravityがノードを読み書きできるようになります。

プロジェクト構造

mkdir notion-mcp-server && cd notion-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk @notionhq/client dotenv
npm install -D typescript @types/node tsx

環境変数の設定

.envファイルを作成します（.gitignoreに必ず追加すること）：

NOTION_TOKEN=secret_YOUR_INTEGRATION_SECRET
NOTION_DATABASE_ID=YOUR_DATABASE_ID_HERE

⚠️ 注意: secret_で始まるトークンやYOUR_API_KEY等のプレースホルダーをそのまま使用してください。実際のトークン値はコードに直書きしないでください。

MCPサーバーの実装

src/notion-mcp-server.tsを作成します：

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { Client } from "@notionhq/client";
import * as dotenv from "dotenv";
 
dotenv.config();
 
// Notion クライアント初期化
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
});
 
const DATABASE_ID = process.env.NOTION_DATABASE_ID!;
 
// MCPサーバー初期化
const server = new Server(
  {
    name: "notion-dev-assistant",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);
 
// ツール一覧の定義
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "get_todo_tasks",
        description:
          "開発タスクDBからTodoステータスのタスク一覧を取得する",
        inputSchema: {
          type: "object",
          properties: {
            priority: {
              type: "string",
              enum: ["High", "Medium", "Low"],
              description: "絞り込む優先度（省略時は全件）",
            },
          },
        },
      },
      {
        name: "get_task_spec",
        description: "特定タスクの仕様書詳細を取得する",
        inputSchema: {
          type: "object",
          properties: {
            page_id: {
              type: "string",
              description: "NotionページID",
            },
          },
          required: ["page_id"],
        },
      },
      {
        name: "update_task_implementation",
        description:
          "タスクの実装サマリーとステータスをNotionに書き込む",
        inputSchema: {
          type: "object",
          properties: {
            page_id: {
              type: "string",
              description: "更新するNotionページID",
            },
            implementation_summary: {
              type: "string",
              description: "実装内容のサマリー（Markdown形式）",
            },
            status: {
              type: "string",
              enum: ["In Progress", "Done", "Blocked"],
            },
            pr_url: {
              type: "string",
              description: "PR URL（オプション）",
            },
          },
          required: ["page_id", "implementation_summary", "status"],
        },
      },
      {
        name: "create_task",
        description: "新しい開発タスクをNotionDBに作成する",
        inputSchema: {
          type: "object",
          properties: {
            name: { type: "string", description: "タスク名" },
            spec: { type: "string", description: "仕様詳細" },
            priority: {
              type: "string",
              enum: ["High", "Medium", "Low"],
            },
          },
          required: ["name", "spec"],
        },
      },
    ],
  };
});
 
// ツール実行ハンドラー
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
 
  switch (name) {
    case "get_todo_tasks": {
      const filter: any = {
        property: "Status",
        select: { equals: "Todo" },
      };
 
      // 優先度フィルターがある場合は AND 条件を追加
      const queryFilter =
        args?.priority
          ? {
              and: [
                filter,
                {
                  property: "Priority",
                  select: { equals: args.priority },
                },
              ],
            }
          : filter;
 
      const response = await notion.databases.query({
        database_id: DATABASE_ID,
        filter: queryFilter,
        sorts: [
          {
            property: "Priority",
            direction: "ascending",
          },
        ],
      });
 
      const tasks = response.results.map((page: any) => ({
        id: page.id,
        name: page.properties.Name?.title?.[0]?.plain_text ?? "",
        priority: page.properties.Priority?.select?.name ?? "",
        status: page.properties.Status?.select?.name ?? "",
        spec:
          page.properties.Spec?.rich_text?.[0]?.plain_text?.slice(
            0,
            200
          ) + "..." ?? "",
      }));
 
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(tasks, null, 2),
          },
        ],
      };
    }
 
    case "get_task_spec": {
      const page = await notion.pages.retrieve({
        page_id: args!.page_id as string,
      }) as any;
 
      const spec =
        page.properties.Spec?.rich_text
          ?.map((t: any) => t.plain_text)
          .join("") ?? "";
      const name =
        page.properties.Name?.title?.[0]?.plain_text ?? "";
      const priority =
        page.properties.Priority?.select?.name ?? "";
 
      return {
        content: [
          {
            type: "text",
            text: `# ${name}\n\n**Priority**: ${priority}\n\n## 仕様詳細\n\n${spec}`,
          },
        ],
      };
    }
 
    case "update_task_implementation": {
      const updates: any = {
        Status: {
          select: { name: args!.status },
        },
        Implementation: {
          rich_text: [
            {
              text: { content: args!.implementation_summary as string },
            },
          ],
        },
      };
 
      if (args?.pr_url) {
        updates["PR URL"] = {
          url: args.pr_url as string,
        };
      }
 
      await notion.pages.update({
        page_id: args!.page_id as string,
        properties: updates,
      });
 
      return {
        content: [
          {
            type: "text",
            text: `✅ タスク ${args!.page_id} を更新しました（Status: ${args!.status}）`,
          },
        ],
      };
    }
 
    case "create_task": {
      const newPage = await notion.pages.create({
        parent: { database_id: DATABASE_ID },
        properties: {
          Name: {
            title: [{ text: { content: args!.name as string } }],
          },
          Status: { select: { name: "Todo" } },
          Priority: {
            select: { name: (args?.priority ?? "Medium") as string },
          },
          Spec: {
            rich_text: [
              { text: { content: args!.spec as string } },
            ],
          },
        },
      });
 
      return {
        content: [
          {
            type: "text",
            text: `✅ タスク作成完了: ${(newPage as any).id}`,
          },
        ],
      };
    }
 
    default:
      throw new Error(`Unknown tool: ${name}`);
  }
});
 
// サーバー起動
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Notion MCP Server running on stdio");
}
 
main().catch(console.error);

ビルドと設定

package.jsonにビルドスクリプトを追加します：

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/notion-mcp-server.js"
  }
}

tsconfig.jsonを作成します：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

ビルドと動作確認：

npm run build
# 出力: dist/notion-mcp-server.js が生成される

Antigravity IDEへのMCP登録

AntigravityにNotion MCPサーバーを登録します。

.antigravity/mcp.jsonを作成（プロジェクトルート）：

{
  "mcpServers": {
    "notion-dev-assistant": {
      "command": "node",
      "args": ["/path/to/notion-mcp-server/dist/notion-mcp-server.js"],
      "env": {
        "NOTION_TOKEN": "${NOTION_TOKEN}",
        "NOTION_DATABASE_ID": "${NOTION_DATABASE_ID}"
      }
    }
  }
}

環境変数の設定（シェル設定ファイルに追加）：

export NOTION_TOKEN="secret_YOUR_INTEGRATION_SECRET"
export NOTION_DATABASE_ID="YOUR_DATABASE_ID"

Antigravity IDEを再起動すると、チャットパネルにNotion連携ツールが認識されます。

実践ワークフロー：仕様書からコードを生成する

MCPが動作したら、いよいよドキュメント駆動開発のワークフローを実践します。

ワークフロー1：Todoタスクの確認と自動コード生成

Antigravityのチャットに以下のプロンプトを入力します：

@notion-dev-assistant Todoステータスで優先度Highのタスクを取得して、
一番優先度の高いタスクの仕様書を読み込んでください。
その仕様に基づいてTypeScript + Next.jsのコードを実装してください。
完成したらテストコードも生成し、実装サマリーをNotionに書き戻してください。

AntigravityとNotionのやり取り（実際の動作例）：

> get_todo_tasks (priority: "High")

[返答]
[
  {
    "id": "abc123-...",
    "name": "ユーザー認証APIの実装",
    "priority": "High",
    "status": "Todo",
    "spec": "JWT認証を使ったRESTful APIを実装する。..."
  }
]

> get_task_spec (page_id: "abc123-...")

[返答]
# ユーザー認証APIの実装

**Priority**: High

## 仕様詳細

エンドポイント:
- POST /api/auth/login: メールアドレスとパスワードで認証
- POST /api/auth/refresh: リフレッシュトークンで新トークン発行
- DELETE /api/auth/logout: セッション無効化

要件:
- JWTトークン（アクセス: 15分, リフレッシュ: 7日）
- bcryptでパスワードハッシュ化
- Prisma + PostgreSQLでユーザーデータ管理
- レートリミット: 10回/分

この仕様を受け取ったAntigravityは、以下のコードを自動生成します：

// src/app/api/auth/login/route.ts
import { NextRequest, NextResponse } from "next/server";
import bcrypt from "bcryptjs";
import jwt from "jsonwebtoken";
import { prisma } from "@/lib/prisma";
import { rateLimit } from "@/lib/rate-limit";
 
const ACCESS_TOKEN_EXPIRES = "15m";
const REFRESH_TOKEN_EXPIRES = "7d";
 
export async function POST(request: NextRequest) {
  // レートリミットチェック
  const ip = request.ip ?? "unknown";
  const { success } = await rateLimit(ip, { limit: 10, window: 60 });
  if (!success) {
    return NextResponse.json(
      { error: "Too many requests" },
      { status: 429 }
    );
  }
 
  const { email, password } = await request.json();
 
  // バリデーション
  if (!email || !password) {
    return NextResponse.json(
      { error: "Email and password are required" },
      { status: 400 }
    );
  }
 
  // ユーザー取得
  const user = await prisma.user.findUnique({ where: { email } });
  if (!user) {
    return NextResponse.json(
      { error: "Invalid credentials" },
      { status: 401 }
    );
  }
 
  // パスワード検証
  const isValid = await bcrypt.compare(password, user.passwordHash);
  if (!isValid) {
    return NextResponse.json(
      { error: "Invalid credentials" },
      { status: 401 }
    );
  }
 
  // トークン生成
  const payload = { userId: user.id, email: user.email };
  const accessToken = jwt.sign(payload, process.env.JWT_SECRET!, {
    expiresIn: ACCESS_TOKEN_EXPIRES,
  });
  const refreshToken = jwt.sign(payload, process.env.JWT_REFRESH_SECRET!, {
    expiresIn: REFRESH_TOKEN_EXPIRES,
  });
 
  // リフレッシュトークンをDBに保存
  await prisma.refreshToken.create({
    data: {
      token: refreshToken,
      userId: user.id,
      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
    },
  });
 
  return NextResponse.json({
    accessToken,
    refreshToken,
    user: { id: user.id, email: user.email },
  });
}

コード生成後、Antigravityは自動でNotionに書き戻します：

> update_task_implementation (
    page_id: "abc123-...",
    status: "In Progress",
    implementation_summary: "JWT認証APIを実装しました。
    - POST /api/auth/login: bcrypt検証 + JWTトークン発行
    - POST /api/auth/refresh: リフレッシュトークン検証・更新
    - DELETE /api/auth/logout: DBからトークン削除
    レートリミット（10回/分）とエラーハンドリングも実装済み。"
  )

✅ タスク abc123-... を更新しました（Status: In Progress）

ワークフロー2：PR説明文の自動生成とNotion連携

実装が完了したら、PR作成も自動化できます：

実装が完了しました。GitHub CLIを使ってPRを作成し、
NotionのタスクステータスをDoneに更新してPR URLを記録してください。

Antigravityは以下を実行します：

# PRを作成（gh CLIを使用）
gh pr create \
  --title "feat: JWT認証API実装 (#abc123)" \
  --body "## 概要
Notionタスク「ユーザー認証APIの実装」の実装PR。
 
## 変更内容
- POST /api/auth/login: bcrypt + JWT認証
- POST /api/auth/refresh: トークン更新
- DELETE /api/auth/logout: セッション無効化
- レートリミット（10回/分）実装
 
## テスト
- Unit tests: 15件（全パス）
- Integration tests: 8件（全パス）"

その後、NotionのPR URLとステータスを自動更新します。

双方向同期の自動化：GitHub Actionsとの統合

より高度な自動化として、GitHubのPRマージイベントをトリガーにNotionを更新するGitHub Actionsを構築できます。

`.github/workflows/notion-sync.yml`

name: Sync Notion on PR Merge
 
on:
  pull_request:
    types: [closed]
 
jobs:
  update-notion:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
 
    steps:
      - name: Extract Notion Page ID from PR title
        id: extract
        run: |
          # PRタイトルから Notion Page ID を抽出
          # 例: "feat: JWT認証API実装 (#abc123-xxxxx)"
          PAGE_ID=$(echo "${{ github.event.pull_request.title }}" \
            | grep -oP '\(#\K[a-z0-9-]+(?=\))')
          echo "page_id=$PAGE_ID" >> $GITHUB_OUTPUT
 
      - name: Update Notion Task Status
        if: steps.extract.outputs.page_id != ''
        env:
          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
        run: |
          PAGE_ID="${{ steps.extract.outputs.page_id }}"
          PR_URL="${{ github.event.pull_request.html_url }}"
 
          # Notion API で直接更新
          curl -s -X PATCH \
            "https://api.notion.com/v1/pages/${PAGE_ID}" \
            -H "Authorization: Bearer ${NOTION_TOKEN}" \
            -H "Content-Type: application/json" \
            -H "Notion-Version: 2022-06-28" \
            -d "{
              \"properties\": {
                \"Status\": {\"select\": {\"name\": \"Done\"}},
                \"PR URL\": {\"url\": \"${PR_URL}\"}
              }
            }"
 
          echo "✅ Notion updated: ${PAGE_ID} → Done"

このワークフローにより、PRのマージ後に自動的にNotionのタスクが「Done」に更新されます。

高度な活用：仕様書テンプレートの設計

ドキュメント駆動開発の効果を最大化するには、Notionの仕様書テンプレートを整備する点が肝心です。以下のテンプレートがAntigravityとの相性に優れています。

推奨仕様書フォーマット

## 機能概要
[何を実装するかを1〜2文で説明]
 
## 対象ユーザー
[この機能を使うのは誰か]
 
## 入力・出力仕様
### 入力
- パラメータ1: 型・バリデーション条件
- パラメータ2: 型・バリデーション条件
 
### 出力
- 成功時: レスポンス形式
- エラー時: エラーコードとメッセージ一覧
 
## ビジネスロジック
1. ステップ1の処理内容
2. ステップ2の処理内容
3. 例外ケースの処理
 
## 技術スタック
- 言語/フレームワーク: TypeScript / Next.js
- DB: PostgreSQL + Prisma
- 依存ライブラリ: bcryptjs, jsonwebtoken
 
## テスト要件
- [ ] 正常系: [具体的なテストケース]
- [ ] 異常系: [エラーケース]
- [ ] パフォーマンス: [閾値]
 
## 参考リンク
- [関連する既存コード]
- [外部APIドキュメント]

このフォーマットで仕様を書くと、Antigravityが構造を正確に解釈してより精度の高いコードを生成できます。

よくあるエラーと対処法

エラー1: MCPサーバーが起動しない

Error: Cannot connect to MCP server "notion-dev-assistant"

原因: パスの設定ミスまたは環境変数未設定

対処法:

# MCPサーバーを単独で起動してテスト
NOTION_TOKEN=secret_xxx NOTION_DATABASE_ID=xxx \
  node /path/to/notion-mcp-server/dist/notion-mcp-server.js
 
# 正常なら "Notion MCP Server running on stdio" と出力される

エラー2: Notion APIが401 Unauthorizedを返す

原因: インテグレーションがデータベースに接続されていない

対処法: Notionのデータベースページで「Connections」→インテグレーションを再接続します。

エラー3: ページIDが見つからない

APIResponseError: Could not find block with ID

原因: Database IDとPage IDの混同、またはIDのフォーマットミス

対処法:

// Notion URLからPage IDを正規化する関数
function normalizePageId(idOrUrl: string): string {
  // UUID形式（ハイフン含む）はそのまま使用
  if (idOrUrl.match(/^[a-f0-9-]{36}$/)) return idOrUrl;
  
  // URLから抽出（32文字の16進数）
  const match = idOrUrl.match(/([a-f0-9]{32})/);
  if (match) {
    const raw = match[1];
    return `${raw.slice(0,8)}-${raw.slice(8,12)}-${raw.slice(12,16)}-${raw.slice(16,20)}-${raw.slice(20)}`;
  }
  throw new Error(`Invalid Notion page ID: ${idOrUrl}`);
}

運用のベストプラクティス

1. Notionデータベースにインデックスを活用する

大規模プロジェクトでは、Notionの「フィルター済みビュー」を活用してタスクを整理します。Antigravityへのプロンプトでも「ビューID」を渡すことで、特定のスプリントや担当者のタスクだけを対象にできます。

2. 実装サマリーの粒度を統一する

Notionへの書き戻しサマリーは、後から読む人（将来の自分を含む）が内容を理解できる粒度で書く点が肝心です。Antigravityへのプロンプトに「以下の形式でサマリーを書いてください」と明示するのが効果的です。

3. セキュリティ：トークン管理の注意点

Notion Internal Integration Secretはデータベース全体への読み書き権限を持ちます。CI/CDに組み込む場合は、必ずGitHub Secretsや環境変数として管理し、リポジトリにコミットしないようにしてください。

4. Notion APIのレートリミット

Notion APIは1秒3リクエストのレートリミットがあります。大量のタスクを処理する場合は、リクエスト間に適切な遅延を設けるか、バッチ処理を実装してください。

個人開発者の視点から（実体験メモ）

まとめ

ここで扱うのはAntigravityとNotion APIを連携させたドキュメント駆動開発（DDD）の完全な実装手順を解説しました。

ポイントを振り返ります：

MCPサーバーの構築: @modelcontextprotocol/sdkと@notionhq/clientでNotion APIをAntigravityのツールとして公開
双方向同期: Notionの仕様書を読んでコードを生成し、実装サマリーを自動でNotionに書き戻す
GitHub Actions連携: PRマージ時にNotionのタスクステータスを自動更新
運用のコツ: 仕様書テンプレートの整備、レートリミット対策、セキュリティ管理

仕様書とコードの乖離は、多くの開発現場で慢性的な課題です。このシステムを導入することで、仕様書が常にコードの「真実の情報源（Single Source of Truth）」として機能するようになります。最初のセットアップに1〜2時間かかりますが、その後の開発速度は確実に向上するはずです。

ドキュメント駆動開発の理論的背景をさらに深く