0
1

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 API × MCPで『ドキュメント駆動AI開発』ワークフローを構築する全手順

0
Posted at

結論: Notionに仕様を書くだけでClaude Codeが実装を始める

Notionに仕様を書くだけでClaude Codeが実装を始める——ドキュメント駆動AI開発の構築手順を全公開します。

この記事で得られることは以下の3つです。

  • Notion → MCP → Claude Code → GitHub を繋ぐ一気通貫ワークフローの設計と構築手順
  • Claude Codeの CLAUDE.md に定義するワークフロー指示の具体例
  • トークン節約やエラーハンドリングなど、実運用で役立つTips

「仕様書を書く → 実装 → PR作成 → ドキュメント更新」をAIが自律的に回す仕組みを、再現可能な手順で解説します。

環境・前提条件

項目 バージョン・条件
Claude Code 最新版（CLI）
Node.js v18以上
Notion ワークスペースの管理者権限
GitHub リポジトリへのpush権限、GitHub CLI(gh)インストール済み
MCP @modelcontextprotocol/server-notion を使用

Notion APIのインテグレーションキーと、対象データベースへの接続許可が事前に必要です。

1. ドキュメント駆動AI開発とは

従来のAI支援開発は「コードを書く部分」だけをAIに任せるものでした。ドキュメント駆動AI開発はその前後も含めて自動化する構想です。

従来のフロー（人間主導）:

  1. 人間が仕様を書く
  2. 人間がAIにプロンプトを渡す
  3. AIがコードを生成する
  4. 人間がPRを作り、ドキュメントを更新する

ドキュメント駆動AI開発のフロー:

  1. 人間がNotionに仕様を書く（ここだけ人間の仕事）
  2. Claude CodeがNotionから仕様を読み取る
  3. Claude Codeが実装・テストを行う
  4. Claude CodeがPRを作成し、Notionのステータスを更新する

つまり、Notionの仕様書がトリガーであり、Single Source of Truthであり、進捗ダッシュボードにもなるという設計です。

2. アーキテクチャ全体図

まず全体のワークフローをシーケンス図で把握しましょう。

ポイントはMCPサーバーがNotion APIのラッパーとして機能し、Claude Codeがツールとして直接呼び出せる点です。Claude Code自身がHTTPリクエストを組み立てる必要はありません。

3. Notion側の設計

3.1 データベースのプロパティ設計

Notion側にタスク管理用のデータベースを作成します。以下のプロパティを設定してください。

プロパティ名 型 用途 値の例
Title タイトル チケット名 ユーザー認証APIの実装
Status ステータス 進捗管理 Ready / In Progress / In Review / Done
Priority セレクト 優先度 High / Medium / Low
Spec リッチテキスト（本文） 仕様の詳細 機能要件・API仕様など
PR URL URL 作成されたPRリンク https://github.com/...
Branch Name テキスト 作業ブランチ名 feat/user-auth-api
Assigned To セレクト 担当（AI or 人間） Claude Code / Human

3.2 ステータス遷移の設計

重要なルールは以下です。

  • ReadyのチケットだけをClaude Codeが拾う
  • Claude Code自身がステータスを Ready → In Progress → In Review と遷移させる
  • Done への遷移は人間が行う（レビュー承認のゲート）

3.3 仕様テンプレート

Notionページの本文には、以下のテンプレートで仕様を記述します。Claude Codeが解釈しやすいように、構造化された見出しを使います。

## 概要
何を作るかの1-2行サマリ

## 機能要件
- [ ] 要件1
- [ ] 要件2

## API仕様（該当する場合）
- エンドポイント: POST /api/users
- リクエスト: { email: string, password: string }
- レスポンス: { id: string, token: string }

## 技術的な制約
- 使用するライブラリやフレームワークの指定
- パフォーマンス要件

## テスト要件
- 正常系テスト
- 異常系テスト

## 対象ファイル
- src/routes/users.ts
- src/services/auth.ts

Tip: 仕様本文はできるだけ簡潔にしてください。長大な仕様はトークンを消費し、Claude Codeの理解精度も落ちます。1チケット1機能の粒度を守ることが重要です。

4. Notion MCPサーバーの設定とClaude Codeへの接続手順

4.1 Notion APIインテグレーションの作成

  1. Notion Developers にアクセス
  2. 「新しいインテグレーション」を作成
  3. 権限は「コンテンツを読み取る」「コンテンツを更新する」を付与
  4. 生成されたインテグレーションキー（ntn_ で始まる文字列）を控える
  5. 対象のNotionデータベースで「コネクション」から作成したインテグレーションを追加

4.2 Claude CodeにNotion MCPサーバーを登録

Claude Codeの設定ファイル ~/.claude/claude_desktop_config.json（デスクトップ版）、またはプロジェクトルートの .mcp.json にMCPサーバーを登録します。

プロジェクトルートの .mcp.json で設定する方法（推奨）:

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

注意: @notionhq/notion-mcp-server はNotion公式が提供するMCPサーバーパッケージです。コミュニティ製の @modelcontextprotocol/server-notion なども存在しますが、公式パッケージの利用を推奨します。利用可能なパッケージは時期により変わる可能性があるため、最新情報は公式リポジトリを確認してください。

4.3 接続確認

Claude Codeを起動して、MCPツールが認識されているか確認します。

claude

起動後、/mcp コマンドで接続中のMCPサーバー一覧を確認できます。

> /mcp

Connected MCP Servers:
  - notion (running)
    Tools: notion_search, notion_get_page, notion_update_page, ...

Notionのツールが表示されれば接続成功です。表示されない場合は、インテグレーションキーの値やJSON構文を確認してください。

5. CLAUDE.mdにワークフローを定義する

プロジェクトルートの CLAUDE.md に、Notionから仕様を読んで実装するワークフローを定義します。これがこの構成の最も重要な部分です。

# CLAUDE.md

## プロジェクト概要
このリポジトリはXXXアプリケーションのバックエンドです。
TypeScript + Express + Prisma で構成されています。

## Notion駆動開発ワークフロー

「Notionから仕様を読んで実装して」と指示された場合、以下の手順で作業すること。

### Step 1: 仕様の取得
1. Notion MCPを使い、タスクデータベース（DB ID: YOUR_DATABASE_ID）からStatusが「Ready」のページを検索する
2. 該当ページの本文（仕様）を取得する
3. 仕様内容をユーザーに提示し、着手してよいか確認する

### Step 2: ステータス更新（着手）
1. 確認が取れたらNotionページのStatusを「In Progress」に更新する
2. Branch Nameプロパティに作業ブランチ名を記入する

### Step 3: ブランチ作成と実装
1. `git checkout -b <branch-name>` で作業ブランチを作成する
2. 仕様に従ってコードを実装する
3. 既存のコード規約・パターンに従うこと
4. 必要に応じてテストを書く

### Step 4: テスト実行
1. `npm test` を実行し、全テストがパスすることを確認する
2. テストが失敗した場合は修正する

### Step 5: PR作成
1. 変更をコミット・プッシュする
2. `gh pr create --title "<チケット名>" --body "<仕様サマリとやったことの要約>"` でPRを作成する
3. PR URLを控える

### Step 6: ステータス更新（レビュー待ち）
1. NotionページのStatusを「In Review」に更新する
2. PR URLプロパティにPRリンクを記入する
3. ユーザーに完了を報告する

## コード規約
- ファイル名: kebab-case
- 関数: camelCase
- テスト: __tests__ディレクトリに配置
- コミットメッセージ: Conventional Commits形式

設計のポイント:

  • Step 3の前に人間の確認を挟む（Step 1で提示 → 承認後に着手）。完全自律にせず、ゲートを設けることで事故を防ぎます
  • データベースIDを CLAUDE.md に直接書くことで、毎回の指示を短縮できます
  • コード規約もこのファイルに集約し、Claude Codeが常に参照できるようにします

6. 実演: チケット作成からPR作成まで

6.1 Notionにチケットを作成

Notionデータベースに以下のチケットを作成します。

  • Title: ヘルスチェックエンドポイントの追加
  • Status: Ready
  • Priority: High
  • 本文:
## 概要
アプリケーションの死活監視用ヘルスチェックエンドポイントを追加する。

## 機能要件
- GET /api/health でステータス200を返す
- レスポンス: { status: "ok", timestamp: "<ISO8601>" }
- データベース接続確認を含む

## テスト要件
- 正常時に200とstatus:"ok"が返ること
- DB接続エラー時に503が返ること

6.2 Claude Codeで実行

claude "Notionから仕様を読んで実装して"

Claude Codeは CLAUDE.md のワークフロー定義に従い、以下を自動実行します。

🤖 Notionデータベースを検索しています...
📋 "Ready"状態のチケットが1件見つかりました:
   - ヘルスチェックエンドポイントの追加（Priority: High）

仕様内容:
  GET /api/health でステータス200を返す...

このチケットに着手してよろしいですか？ (y/n)

y と回答すると、実装が始まります。

🔄 Notionステータスを "In Progress" に更新しました
🌿 ブランチ feat/health-check-endpoint を作成しました
📝 src/routes/health.ts を作成中...
📝 src/__tests__/health.test.ts を作成中...
✅ テスト実行: 2 passed, 0 failed
🔀 PR #42 を作成しました: https://github.com/your-org/your-repo/pull/42
🔄 Notionステータスを "In Review" に更新しました

完了しました！PR: https://github.com/your-org/your-repo/pull/42

黄色のノード（承認・レビュー）が人間のタッチポイントです。それ以外はすべてClaude Codeが自律的に処理します。

7. 運用Tips

7.1 トークン節約のためのページ構造最適化

Notion MCPはページの全内容を取得するため、無駄な情報があるとトークンを消費します。

やるべきこと:

  • 仕様は1チケット1ページ、1ページ1機能を徹底する
  • 画像・埋め込みブロックは避け、テキストベースで記述する
  • 参考資料は本文に含めず、別ページへのリンクにする
  • 不要なコメントやログは仕様ページに残さない

目安: 1チケットの仕様は500〜1,500文字程度に収めるとトークン効率が良いです。

7.2 エラー時のフォールバック設計

Claude Codeの実行中にエラーが発生するケースへの備えも重要です。

CLAUDE.md に追記するフォールバックルール:

## エラー時のルール
- テストが3回修正しても通らない場合:
  Notionステータスを「Blocked」に変更し、
  エラー内容をページのコメントに記載して作業を中断する
- Notion APIへの接続に失敗した場合:
  ターミナルにエラーを表示し、ステータス更新は手動で行うよう報告する
- 仕様に不明点がある場合:
  実装を始めず、不明点をリストアップしてユーザーに質問する

7.3 複数チケットの一括処理

複数の「Ready」チケットがある場合の運用ルールも定義しておきましょう。

## 複数チケット時のルール
- Priorityが「High」のチケットを優先する
- 同じPriorityの場合、作成日が古い順に処理する
- 1回の実行で処理するのは最大3チケットまでとする
- チケット間の依存関係がある場合はユーザーに確認する

7.4 セキュリティ上の注意

  • Notionインテグレーションキーは .mcp.json に直接書くとリポジトリにコミットされる危険があります。.mcp.json を .gitignore に追加するか、環境変数経由で渡す設計にしてください
  • CLAUDE.md にデータベースIDを記載する場合も、公開リポジトリでは注意が必要です

まとめ

  • Notion × MCP × Claude Codeで、仕様書を起点にした一気通貫の開発ワークフローが構築できる。 人間は仕様を書くことと最終レビューに集中でき、実装・テスト・PR作成・ステータス管理はClaude Codeが自律的に処理します
  • CLAUDE.mdのワークフロー定義が鍵。 ステップ化された指示と、人間の確認ゲート、エラー時のフォールバックを明文化することで、再現性の高い自動化が実現します
  • 運用では「1チケット1機能」の粒度と、トークン節約を意識したページ設計が重要。 巨大な仕様を渡さない、セキュリティに配慮するなど、実運用で効いてくるポイントを押さえましょう

参考リンク

0
1
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
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?