0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@hikariclaude01(光 久朗土)

【実践】Claude Code × Notion MCPで開発ドキュメントを自動生成する仕組みを作った

0
Last updated at Posted at 2026-03-25
---
title: "【実践】Claude Code × Notion MCPで開発ドキュメントを自動生成する仕組みを作った"
tags:
  - ClaudeCode
  - MCP
  - Notion
  - AI
  - 開発効率化
private: false
---

**『コード書いたらNotionのドキュメントも勝手に更新されてほしい』——その夢、MCPで実現できます。**

## 結論：Claude Codeの作業中にNotionドキュメントを自動で生成・更新できる

Claude CodeにNotion MCP Serverを接続すると、**コードを書きながら同時にNotionのドキュメントを生成・更新**できます。私はこの仕組みを1週間運用し、「ドキュメントが腐る」問題をほぼ解消できました。

この記事では、導入手順・プロンプト設計・運用所感まで、実践ベースでお伝えします。

---

## 1. なぜ開発ドキュメントは腐るのか — 自動化の動機

開発ドキュメントが陳腐化する原因は明確です。

- **コードとドキュメントの更新タイミングがずれる**：実装を終えた後にドキュメントを書く気力がない
- **「あとで書く」が永遠に来ない**：PRのマージが優先され、ドキュメント更新は後回し
- **書く場所が分散している**：README、Notion、Confluence…どこに何があるかわからない

私のチームでは、Notionを開発ドキュメントの中心に据えていましたが、実装とのズレが常に2〜3スプリント分ありました。

### 理想の状態

「コードを変更したら、その変更内容がNotionに反映される」——これをClaude Code × MCP で実現します。

```mermaid
sequenceDiagram
    participant Dev as 開発者
    participant CC as Claude Code
    participant MCP as Notion MCP Server
    participant API as Notion API
    participant NP as Notionページ

    Dev->>CC: コード変更 + ドキュメント更新指示
    CC->>MCP: MCP tool呼び出し（ページ検索/作成/更新）
    MCP->>API: HTTPS リクエスト
    
    alt 成功
        API->>NP: ページ更新
        NP-->>API: 200 OK
        API-->>MCP: 成功レスポンス
        MCP-->>CC: 結果返却
        CC-->>Dev: 「Notionを更新しました」
    else 認証エラー (401)
        API-->>MCP: 401 Unauthorized
        MCP-->>CC: エラー返却
        CC-->>Dev: 「認証トークンを確認してください」
    else ページ未検出 (404)
        API-->>MCP: 404 Not Found
        MCP-->>CC: エラー返却
        CC-->>Dev: 「対象ページが見つかりません。IDを確認してください」
    end

2. Notion MCP Serverの導入手順と認証設定

前提条件

項目 バージョン / 要件
Claude Code 最新版（CLIで claude --version 確認）
Node.js v18以上
Notionアカウント ワークスペースの管理者権限
OS macOS / Linux（Windowsの場合はWSL2推奨）

Step 1：Notion Integrationの作成

  1. Notion Developers にアクセス
  2. 「New integration」をクリック
  3. 以下を設定：
    • Name: claude-code-docs（任意）
    • Associated workspace: 対象のワークスペースを選択
    • Capabilities: 「Read content」「Update content」「Insert content」にチェック
  4. 「Submit」→ 表示された Internal Integration Secret をコピー

⚠️ 注意: Secretは ntn_ で始まる文字列です。一度しか表示されないので安全な場所に保管してください。

Step 2：NotionページにIntegrationを接続

ドキュメントを管理するNotionページ（または親データベース）を開き：

  1. 右上の「…」メニュー →「Connections」
  2. 作成した claude-code-docs を検索して追加

これを忘れるとAPIからアクセスできません。 最も多いハマりポイントです。

Step 3：Notion MCP ServerをClaude Codeに登録

Claude Codeの設定ファイルにMCPサーバーを追加します。

# プロジェクトルートで実行
claude mcp add notion-server -e NOTION_API_KEY=ntn_xxxxxxxxxxxxx -- npx -y @notionhq/notion-mcp-server

これにより、.claude/mcp.json（またはプロジェクト設定）に以下のような設定が追加されます。

{
  "mcpServers": {
    "notion-server": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "ntn_xxxxxxxxxxxxx"
      }
    }
  }
}

💡 Tips: NOTION_API_KEY を直接ファイルに書きたくない場合は、環境変数経由で渡すことも可能です。.env に記載して -e NOTION_API_KEY のように参照させましょう。

Step 4：接続確認

Claude Codeを起動して、MCP接続を確認します。

claude

起動後に /mcp コマンドで接続状態を確認できます。

> /mcp

MCP Servers:
  notion-server: connected ✅
    Tools: notion_search, notion_create_page, notion_update_page, ...

connected と表示されれば成功です。

3. Claude Codeからノーション連携する具体的プロンプト設計

MCP接続ができたら、次はどう指示すればClaude Codeが良いドキュメントを生成してくれるかです。ここがこの仕組みの肝になります。

基本方針：CLAUDE.mdにドキュメント運用ルールを書く

プロジェクトルートの CLAUDE.md にルールを記載することで、毎回指示しなくてもドキュメント生成が走るようにできます。

## ドキュメント自動更新ルール

### トリガー
- 新しいAPIエンドポイントを追加したとき
- 既存の関数シグネチャを変更したとき
- 新しい環境変数を追加したとき

### 更新先
- Notion データベースID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- 親ページID: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy

### ドキュメント構成
各ページは以下の構成で作成・更新すること:
1. 概要（何をするAPIか、1〜2文）
2. エンドポイント情報（メソッド、パス、認証要否）
3. リクエスト/レスポンス例（JSON）
4. 注意事項・制約

実践プロンプト例

パターン①：新規APIのドキュメントを自動生成

src/routes/users.ts に GET /api/users/:id エンドポイントを追加して。
実装後、Notionの開発ドキュメントページ配下にAPIドキュメントも作成して。

Claude Codeは以下の手順で動作します：

  1. src/routes/users.ts にコードを実装
  2. Notion MCP の notion_search でドキュメントページを検索
  3. notion_create_page で新しいサブページを作成
  4. API仕様を構造化して記載

パターン②：既存ドキュメントの更新

src/routes/users.ts の GET /api/users/:id にクエリパラメータ `fields` を追加して。
対応するNotionドキュメントも更新して。

パターン③：一括ドキュメント生成

src/routes/ 配下の全エンドポイントを解析して、
Notionの「API仕様書」ページ配下にまとめてドキュメントを生成して。
既存ページがあれば更新、なければ新規作成して。

プロンプト設計のコツ

ポイント 悪い例 良い例
更新先を明示 「ドキュメント書いて」 「NotionのAPIドキュメントページに書いて」
構成を指定 「いい感じに」 「概要・エンドポイント・リクエスト例・レスポンス例の順で」
既存との整合性 （言及なし） 「既存ページがあれば更新、なければ新規作成」

4. 実際に生成されたドキュメントのBefore/Afterと運用1週間の所感

Before：手動運用時代のドキュメント

実際に私のチームで起きていた状態です。

## ユーザー取得API

GET /api/users/:id

ユーザー情報を返す。

※詳細はソースコード参照

…これだけ。リクエストパラメータもレスポンス例もなし。「ソースコード参照」は実質「ドキュメントなし」と同義です。

After：Claude Code × Notion MCP生成のドキュメント

同じAPIについて、Claude Codeが生成したNotionドキュメントは以下のようになりました。

## GET /api/users/:id
ユーザーIDを指定して、ユーザーの詳細情報を取得します。

### エンドポイント
- メソッド: GET
- パス: /api/users/:id
- 認証: Bearer Token（必須）

### パスパラメータ
| パラメータ | 型     | 必須 | 説明           |
|-----------|--------|------|---------------|
| id        | string | ✅   | ユーザーのUUID |

### クエリパラメータ
| パラメータ | 型     | 必須 | 説明                          |
|-----------|--------|------|------------------------------|
| fields    | string | -    | 取得フィールドのカンマ区切り指定 |

### レスポンス例（200 OK）
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "田中太郎",
  "email": "tanaka@example.com",
  "createdAt": "2025-01-15T09:00:00Z"
}

### エラーレスポンス
- 401: 認証トークンが無効
- 404: 指定されたIDのユーザーが存在しない

### 注意事項
- `fields` 未指定時は全フィールドを返却
- レスポンスの `email` はリクエスト元の権限によりマスクされる場合あり

コードの実装内容を読み取って、パラメータ・レスポンス構造・エラーケースまで自動で記載してくれます。

運用1週間の所感

よかった点

  • ドキュメントの鮮度が劇的に改善: コード変更と同時に更新されるため、ズレが発生しない
  • 記載粒度が安定: CLAUDE.mdでテンプレートを定義しているため、人によるバラつきがなくなった
  • レビューコストの削減: ドキュメントの「存在確認」が不要に。内容の正確性チェックだけで済む

注意が必要な点

  • Notion APIのレート制限: 大量ページの一括更新時には注意が必要（3リクエスト/秒の制限あり）
  • ブロック構造の制約: Notion APIでは複雑なレイアウト（トグルのネストなど）が扱いにくい場合がある
  • 生成内容の検証は必要: AIが生成したドキュメントが100%正確とは限らない。特にエッジケースの記述はレビューが必要

定量的な変化

指標 Before After
ドキュメント更新頻度 月1〜2回 ほぼ毎日（コード変更時）
1エンドポイントのドキュメント作成時間 15〜30分 1〜2分（自動生成 + 確認）
ドキュメントとコードのズレ 2〜3スプリント ほぼリアルタイム

まとめ

  • Claude Code × Notion MCPで、コード実装と同時にドキュメントが自動生成・更新される仕組みを構築できる
  • CLAUDE.mdにルールとテンプレートを定義しておくことで、一貫性のあるドキュメントが安定して生成される
  • 完全自動化ではなく「自動生成 + 人間レビュー」のハイブリッド運用が現時点でのベストプラクティス

参考リンク

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?