---
name: notion-bulk-insert
description: Notion Database への大量レコード（数百〜数千件）一括投入を、DB別プリセット（YAML宣言）で再利用可能にする。源JSON→pages配列を分割emit→呼び出し側がnotion-create-pages MCPで投入。複数プロジェクトで使えるようプリセットを追加することで運用継続。
metadata:
  trigger_keywords:
    - Notion DB へバルクインサート
    - 数百件をNotionに一括投入
    - データソースに大量レコードを入れる
    - DPro CR をNotionに投入
    - 参考記事ブロックをNotionに投入
    - Notion バルク投入
---

# notion-bulk-insert

## 関連資産

- このSkill固有:
  - scripts: `.agents/skills/notion-bulk-insert/scripts/` (emit_pages.py)
  - 設定: `.agents/skills/notion-bulk-insert/presets.yaml`
- 共有:
  - 共通script: `tools/run_with_gui_env.zsh`, `tools/dpro_mcp_bridge.mjs`, `tools/gemini_model_policy.mjs`
  - 共有reference: `knowledge/skill-routing.md`, `knowledge/operating-principles.md`, `knowledge/production-gates.md`
  - 共有template: `templates/work_order_minimum.yaml`, `templates/blocked_handoff.md`
  - 運用ドキュメント: `docs/agent_operating_doctrine.md`, `docs/distribution_run_log.md`

Notion Database に **数百件規模** のレコードを一括投入するための再利用可能 Skill。
DB ごとの「カラム→プロパティ変換規則」を YAML で宣言する（ピボット契約3：用途別ルールはYAML）。

## なぜ必要か

**検証ループ002 の発見（2026-04-30）**:
- DB2 (349件) を MCP `notion-create-pages` で投入する際、1回のツール呼出に inline で渡せるサイズに制約がある
- 50件×7バッチを毎回手書きで書き起こすと context を大量消費
- 同じことをDB4-v2 (183件) でも繰り返す必要がある → Skill化が筋

## いつ発火させる

- ユーザーが「Notion DB へ ○○件投入」と言ったとき
- 既存の Notion records JSON（DB1〜5用 `records.json` 等）から大量投入する直前
- 新規 DB を作って初期データ流し込みする時

## 使い方

### Step 1: プリセット選定または追加

`presets.yaml` を確認し、対象 DB のプリセットがあるか確認：

```yaml
presets:
  example_agent-demo-loop-db2:
    data_source_id: "<redacted_uuid>"
    title_property: "item_id"
    column_truncation:
      ad_sentence: 150
      ad_all_sentence: 250
      narration: 250
      advertiser_name: 80
      virtual_enemy: 100
    json_array_columns: [appeal_axis, n1_attr]
    optional_columns: [transition_url, production_url]
```

無ければ新規プリセットを追加する。プリセット定義のみで再利用可能になる（コードに分岐を書かない）。

### Step 2: emit 実行

```bash
python3 .agents/skills/notion-bulk-insert/scripts/emit_pages.py \
  --records <path/to/records.json> \
  --preset example_agent-demo-loop-db2 \
  --presets .agents/skills/notion-bulk-insert/presets.yaml \
  --offset 99 \
  --limit 50 \
  --out /tmp/notion_batch.json
```

オプション：
- `--offset N` 既存投入済件数（重複防止）
- `--limit N` 1バッチサイズ（デフォルト50）
- `--out PATH` 出力先 JSON

stdout には件数情報（"BATCH offset=99 limit=50 emitted=50"）。

### Step 3: 呼び出し側（Codex）が MCP 経由で投入

```python
# Codexが /tmp/notion_batch.json を読み、その内容を
# mcp__744468eb-...__notion-create-pages の pages 引数に渡す
```

Step 2-3 を全件投入し終えるまで繰り返す。

### Step 4: 投入完了後、HANDOVER と reference に記録

- HANDOVER.md に「DB○○ N件→M件 投入完了」を追記
- `docs/distribution_run_log.md` または案件HANDOVERの投入状況テーブルを更新

## 制約・注意

- **重複投入防止**：`--offset` で既存件数をスキップ。または事前に notion-search で existing item_id を取得して dedup
- **API レート制限**：Notion MCP の `pages: max 100` 制約を尊重。1呼出50件推奨
- **Skill 自身は MCP を呼ばない**：emit のみ。MCP 呼出は Codex メイン会話で行う（サブエージェントには MCP 権限なし）

## 違反時の degraded mode 報告

- プリセット未定義のままハードコードで投入した場合、HANDOVER に記録
- 重複投入が発生した場合、duplicate item_id 一覧を出力

## 関連

- 現行運用正本：`marketing_agentic_rag_os_spec_pack/docs/agent_operating_doctrine.md`
- 先行例：`.agents/skills/lp-image-optimizer/`