メインコンテンツまでスキップ

docs↔︎Notion 紐付け・新規作成フローガイド

本プロジェクトでは、コードと一体化した仕様書（Markdown）と、ドキュメント閲覧・タスク管理に適した Notion を双方向で連携させてハイブリッドに管理します。

本ガイドでは、Notion 上にまだ仕様書ページが存在しない状態から、新規にページを作成し、ローカルの Markdown ファイルと紐付けるための詳細な手動手順について解説します。

1. 紐付けの基本設計（仕組み）​

Markdownファイル（ローカル）と Notionページは、以下の 「双方向のキー」 で紐付けられます。

  • Markdown 側 (Frontmatter): すべての仕様書ファイルの冒頭に、対応する Notion の notion_page_id を保持します。
  • Notion 側 (Properties): 対応する Notion ページのプロパティ（File Path）に、プロジェクトルートからの相対パス（例: docs/files/specifications/auth/details.md）を設定します。

2. 新規作成・紐付けの 5 ステップ​

Notion 上にページがまだ存在しない仕様書を新しく作成し、紐付ける場合は、以下の手順に従って作業（事務作業）を行ってください。

1️⃣ Step 1：Notion 側にページを新規作成する​

  1. Notion を開き、仕様書を管理しているデータベースまたは親ページを開きます。
  2. 仕様書の種類（Sho-Room、備品管理、Workers等）に応じた適切な場所（データベースの新規行、またはサブページ）にページを新規作成します。
  3. ページのタイトルを設定します（例: 認証システム仕様（auth/details））。

2️⃣ Step 2：Notion 側に File Path プロパティを追加・設定する​

  1. 作成した Notion ページの上部にあるプロパティ追加エリアから、新しいプロパティを追加します。
    • プロパティ名: File Path
    • 種類: テキスト (Text)
  2. 作成した File Path プロパティに、リポジトリのルートからのファイル相対パスを入力します。
    • 例: docs/files/specifications/auth/details.md
    • ⚠️ 注意: パスの先頭に / (スラッシュ) は付けず、拡張子 .md まで含めて正確に記述してください。

3️⃣ Step 3：Notion ページの URL から「ページ ID」を抽出する​

  1. Notion ページの右上にある 「リンクをコピー」、またはブラウザのアドレスバーからページの URL を取得します。
    • URL の例: https://www.notion.so/university/auth-details-1234567890abcdef1234567890abcdef
  2. URL の末尾にある 32桁の英数字（ハイフンを含まない英数字の羅列） を抽出します。これが ページ ID です。
    • 抽出例: 上記 URL の場合、1234567890abcdef1234567890abcdef がページ ID となります。

4️⃣ Step 4：Markdown 側（ローカル）にページ ID を追記する​

  1. 対応するローカルの仕様書 Markdown ファイル（例: docs/files/specifications/auth/details.md）を開きます。
  2. ファイルの冒頭（Frontmatter）の notion_page_id に、Step 3 で抽出したページ ID を記述します。
---
notion_page_id: "1234567890abcdef1234567890abcdef"
---

# 認証システム（auth/details）
...

⚠️ 注意: 既に sidebar_position などの他の Frontmatter が存在する場合は、その下に追記してください。また、IDは " (ダブルクォーテーション) で囲んでください。

5️⃣ Step 5：Markdown の中身を Notion へ初期移行する​

  1. ローカルの Markdown のコンテンツ全体をコピーします。
  2. Notion ページの本文エリアにそのまま貼り付けます。
  3. 貼り付け後、以下のフォーマットが正常に変換されているか確認・微調整します。
    • Mermaid図: Notion側で 「コード」ブロック として貼り付けられていることを確認し、ブロックの言語設定を Mermaid に変更します（Notion上で図としてレンダリングされるようになります）。
    • 箇条書きの空行: ガイドラインに従い、箇条書き（-, * 等）の直前には空行が入っていることを確認してください（Notionでブロックが崩れるのを防ぐため）。

PRがマージされることで、リポジトリの main ブランチの仕様書に Notion ページ ID が完全に刻まれ、将来的な自動同期ツール（Notion MCP）導入時の準備が万全となります。

4. Notion MCP（AI自動同期）のセットアップ​

手動でのコンテンツ貼り付けはミスが発生しやすく手間がかかるため、本プロジェクトでは Notion MCP (Model Context Protocol) サーバー を用いた AI エージェントによる自動同期をサポートしています。

セットアップを完了することで、AI エージェントに「仕様書を Notion に同期して」と指示するだけで、ローカルの変更が Notion 上の対応するページへ自動反映されるようになります。

1️⃣ Step 1：Notion 内部インテグレーションの作成​

  1. Notion My Integrations にアクセスします。
  2. 「+ 新しいインテグレーション」 をクリックします。
  3. 以下の設定を入力し、「送信」をクリックします：
    • 名前: Soshosai Docs Sync (任意)
    • ワークスペース: 同期したい Notion ワークスペースを選択
    • タイプ: 内部インテグレーション (Internal)
  4. 生成された 「シークレット インテグレーション トークン」（secret_... で始まる値）をコピーし、安全な場所に控えておきます。
  5. 「インテグレーションの権限」 タブで、以下の権限が有効になっていることを確認します：
    • コンテンツを読み取る
    • コンテンツを更新する
    • コンテンツを挿入する

2️⃣ Step 2：Notion ページへのコネクト追加​

Notion のセキュリティ上、インテグレーションは明示的に共有されたページにしかアクセスできません。

  1. 同期対象の親ページ（または仕様書データベース）を Notion で開きます。
  2. 画面右上の 「...」 (その他のアクション) ページ設定 メニューをクリックします。
  3. 「コネクトを追加」 (Add connections) を選択し、Step 1 で作成したインテグレーション名（例: Soshosai Docs Sync）を検索して追加します。
  4. コネクト追加の確認ダイアログが表示されたら「アクセスを許可」します。

    [!NOTE] 親ページにコネクトを追加すると、その配下にあるすべてのサブページやデータベースにも自動的に権限が継承されます。

3️⃣ Step 3：MCP 設定ファイルの構成​

プロジェクトのルートディレクトリに、Notion MCP サーバーを起動するためのサンプル設定ファイル mcp-config.example.json が用意されています。

これをベースに、お使いの AI クライアント（Claude Desktop や VS Code (Roo Code 等)、または CLI ツール）に Notion MCP を設定します。

Claude Desktop の設定例​

~/Library/Application Support/Claude/claude_desktop_config.json（macOS の場合）を開き、mcpServers ブロックに Notion MCP サーバーの設定を追加します：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-notion"
      ],
      "env": {
        "NOTION_API_TOKEN": "YOUR_NOTION_INTEGRATION_TOKEN"
      }
    }
  }
}

※ YOUR_NOTION_INTEGRATION_TOKEN を Step 1 で取得した secret_... トークンに置き換えてください。

プロジェクトローカル設定の例​

Antigravity などのプロジェクト個別設定に対応したエージェントを使用する場合は、プロジェクトルートの .mcp_config.json 等に同様の設定を転記して使用します。

5. AI を用いた自動同期の実行方法​

セットアップ完了後、Notion MCP が有効化された AI エージェントに対して、以下のように指示を出すことで自動同期を実行できます。

💡 指示プロンプトの例​

仕様書の Notion 同期を指示する例

修正した auth/details.md の変更内容を、Notion ページに同期して。
notion_page_id はフロントマターに書いてあるものを使ってね。

🤖 AI が内部で行う処理​

  1. AI が指定された仕様書（Markdown）からフロントマター notion_page_id（例: 12345678...）を読み取ります。
  2. AI が notion MCP サーバーの update_page または append_block 等のツールを使用して、ローカルの Markdown コンテンツを Notion のブロック形式に変換しながら、該当する Notion ページの内容を書き換えます。
  3. 差分が正しく反映されたことを AI が確認し、結果を報告します。

これにより、手動でのコピペ作業を排除し、仕様書の一貫性を極めて高い品質で維持し続けることが可能になります。