**『要件はNotionに書いて、実装はClaude Codeに任せて、PRまで自動で出る』**──そんなワークフローを実際に構築して2週間運用した記録を、構成図・コマンド・ハマりどころ付きで全公開します。

結論：何ができるようになるか

Notionに要件を書くだけで、Claude Codeが要件を読み取り、実装し、GitHubにPRを作成するところまでを1コマンドで完結させるワークフローを構築できます。従来90分かかっていた「要件確認→実装→PR作成」のサイクルが、実測で約30分に短縮されました。

この記事では、MCP（Model Context Protocol）サーバー2つの構築手順から、カスタムスラッシュコマンドの設計、2週間運用で踏んだ5つの落とし穴まで、再現可能な粒度で解説します。

環境・前提条件

項目	バージョン / 条件
Claude Code	最新版（CLI）
Node.js	v20以上
OS	macOS Sonoma（Linux/WSL2でも動作確認済み）
Notionアカウント	ワークスペースの管理者権限
GitHubアカウント	対象リポジトリへのwrite権限
シェル	bash / zsh

1. 完成形のワークフロー全体像

まず完成形を見てください。以下が、Notionに要件を書いてからPRが作成されるまでの全体の流れです。

ポイントは、Claude CodeがMCPサーバーを介してNotionとGitHubの両方にアクセスできる点です。開発者が触るのは「Notionに要件を書く」と「スラッシュコマンドを1回叩く」の2アクションだけです。

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

2-1. Notion MCPサーバーのセットアップ

Step 1：Notionインテグレーションを作成する

Notion Developers にアクセス
「New integration」からインテグレーションを作成
権限は「Read content」「Update content」「Insert content」を付与
Internal Integration Tokenを控える

Step 2：対象ページにインテグレーションを接続する

要件を管理するNotionデータベースで、右上の「…」→「接続」→ 作成したインテグレーションを追加します。これを忘れるとAPI経由でアクセスできません（ハマりポイント①）。

Step 3：Claude Codeの設定ファイルにNotion MCPを追加する

プロジェクトルートの .mcp.json に以下を記述します。

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

注意：OPENAPI_MCP_HEADERS の値はJSON文字列をエスケープして渡す必要があります。ここのフォーマットミスが原因で接続エラーになるケースが非常に多いです。

2-2. GitHub MCPサーバーのセットアップ

Step 1：GitHub Personal Access Token（PAT）を発行する

GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens から作成します。

必要な権限：

Contents: Read and write
Pull requests: Read and write
Metadata: Read-only

Step 2：Claude Codeの設定ファイルにGitHub MCPを追加する

先ほどの .mcp.json に追記します。

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

Step 3：接続確認

Claude Codeを起動し、MCPサーバーの接続状態を確認します。

claude

起動後、プロンプトに以下を入力して疎通を確認します。

Notionの要件データベースからページ一覧を取得して

GitHubリポジトリ owner/repo のブランチ一覧を取得して

両方のレスポンスが正常に返れば、MCPサーバーの構築は完了です。

2-3. 認証情報の管理

.mcp.json は .gitignore に必ず追加してください。 トークンがリポジトリにコミットされると重大なセキュリティインシデントになります。

echo ".mcp.json" >> .gitignore

3. カスタムスラッシュコマンドで一気通貫を実現する

3-1. スラッシュコマンドの設計

Claude Codeでは、.claude/commands/ ディレクトリにMarkdownファイルを配置することでカスタムスラッシュコマンドを定義できます。

mkdir -p .claude/commands

3-2. ワークフロー実行コマンド

.claude/commands/workflow-run.md を作成します。

---
description: Notionから要件を取得し、実装してGitHub PRを作成する
---

# 一気通貫ワークフロー

以下の手順を順番に実行してください。

## Step 1: 要件取得
Notion MCPを使って、以下のページIDから要件を取得してください。
ページID: $ARGUMENTS

取得した要件から以下を抽出してください：
- タスクタイトル
- 機能要件（箇条書き）
- 受け入れ条件
- 対象ファイル・モジュール（記載がある場合）

## Step 2: 実装計画
要件に基づき、以下の形式で実装計画を立ててください：
1. 変更するファイルの一覧
2. 各ファイルの変更概要
3. テスト方針

計画を私に提示し、承認を得てから次に進んでください。

## Step 3: 実装
承認された計画に基づいてコードを実装してください。
- ブランチ名: feat/<タスクタイトルをkebab-case化>
- コミットメッセージ: Conventional Commits形式
- 既存テストが壊れていないことを確認

## Step 4: PR作成
GitHub MCPを使ってPRを作成してください。
- タイトル: タスクタイトル
- 本文: 要件の要約、変更内容、テスト結果を含める
- ベースブランチ: main

## Step 5: Notion更新
Notion MCPを使って、元の要件ページに以下を追記してください：
- PR URL
- ステータスを「PR作成済み」に変更

3-3. 使い方

claude
> /workflow-run 1a2b3c4d-5e6f-7890-abcd-ef1234567890

引数にNotionのページIDを渡すだけです。ページIDはNotionのURLから取得できます。

https://www.notion.so/Your-Page-Title-1a2b3c4d5e6f7890abcdef1234567890
                                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                      このハイフンなしの32文字がページID

3-4. 補助コマンド：要件確認のみ

実装せずに要件だけ確認したい場面も多いので、確認専用コマンドも作りました。

.claude/commands/req-check.md:

---
description: Notionの要件ページを読み取り、実装計画だけ提示する
---

Notion MCPを使ってページID $ARGUMENTS の内容を取得し、
以下の形式で実装計画を提示してください。実装は行わないでください。

- 変更ファイル一覧
- 各ファイルの変更概要
- 想定される影響範囲
- 推定作業時間

4. 2週間運用で踏んだ5つの落とし穴

落とし穴①：Notionページのインテグレーション接続忘れ

症状：Could not find page with ID: xxxxx エラー

Notionは、ページ単位（正確には親ページ単位）でインテグレーションへのアクセス許可を明示的に付与する必要があります。新しいページを作るたびにこの接続を忘れがちでした。

対策：要件管理用のデータベースを1つ決め、そのデータベース自体にインテグレーションを接続しておく。データベース内の全ページに権限が継承されます。

落とし穴②：トークン爆発（Context Window超過）

症状：Notionの要件ページが長大だと、取得したテキストだけでコンテキストウィンドウの大部分を消費し、実装フェーズでトークンが足りなくなる。

対策：

要件ページは1ページ1機能を徹底（目安：2,000文字以内）
Notionのページに「Claude Code向け要約」セクションを設け、要約だけ先頭に配置
プロンプトに「要件の要約セクションのみ取得してください」と明記

落とし穴③：Notion APIのレート制限

症状：短時間にワークフローを連続実行すると 429 Too Many Requests が発生。

Notion APIのレート制限は平均3リクエスト/秒です。要件取得→ステータス更新で複数回APIを叩くため、連続実行時に引っかかります。

対策：プロンプトに「Notion APIへのリクエスト間隔は最低1秒空けてください」と明記。完全な解決ではありませんが、実用上は問題なくなりました。

落とし穴④：PR差分の暴走

症状：Claude Codeが要件を拡大解釈し、指示外のファイルまでリファクタリングして巨大なPRが生成される。

対策：

スラッシュコマンド内に「変更は要件に記載されたスコープに厳密に限定してください。スコープ外の改善を見つけた場合は報告のみ行い、変更は加えないでください」と明記
CLAUDE.md にもプロジェクト全体のルールとして記載

落とし穴⑤：ブランチの競合

症状：同名ブランチが既に存在する場合にPR作成が失敗する。

対策：ブランチ名にタイムスタンプを含める指示を追加。

ブランチ名: feat/<タスクタイトルをkebab-case化>-<YYYYMMDDHHmm>

5. 定量結果：従来フロー比の作業時間比較

2週間で計18タスクをこのワークフローで処理しました。比較対象は、同種のタスクを従来の手動フローで行った場合の平均時間です。

工程	従来フロー	本ワークフロー	削減率
要件確認・理解	15分	5分（Notionから自動取得+要約）	-67%
実装	45分	15分（Claude Codeによる実装）	-67%
テスト実行・修正	15分	5分（自動テスト実行+修正）	-67%
PR作成・記述	15分	2分（自動生成）	-87%
合計	90分	27分	-70%

補足：上記は「小〜中規模の機能追加タスク（新規ファイル1-3個、変更ファイル2-5個程度）」の平均です。大規模なアーキテクチャ変更には適用していません。

定性的な効果

コンテキストスイッチの削減：Notionを見る→エディタで実装→GitHubでPR作成、という画面遷移がなくなった
PR品質の向上：PR本文に要件の要約が自動記載されるため、レビュアーが文脈を理解しやすくなった
要件とコードのトレーサビリティ：NotionページにPRリンクが自動追記されるため、要件→実装の追跡が容易に

まとめ

MCPサーバー2つ（Notion + GitHub）をClaude Codeに接続することで、要件取得からPR作成までの一気通貫ワークフローを構築できる
カスタムスラッシュコマンドにワークフロー全体を定義すれば、1コマンドで実行可能。ただしトークン爆発・差分暴走への対策をプロンプト設計に組み込むことが重要
2週間18タスクの実測で作業時間を約70%削減。特にPR作成の自動化（87%削減）の効果が大きい

参考リンク