Shunsuke Kataoka Blog

TL;DR

Claude Code（CLI ハーネス）上に、個人ブログ用の執筆エージェントを実装しました。
構成は「Skill（入口）+ Sub-agent（執筆・品質検査）+ Protocol（運用ルール）」の3層です。
git push で Markdown 投稿する想定でしたが、投稿先が Notion CMS 駆動だったため、MCP（Model Context Protocol）経由の Notion API フローへ切り替えました。

個人ブログ（blog.skllll.com）を Next.js 16 + Notion CMS の「ヘッドレス Notion」型で運営しています。課題は「ネタは浮かぶのに書き始めまでの摩擦が大きい」というありふれたもの。本業では AI 活用を軸とした業務改善に取り組んでおり、手元では Claude Code を個人 AI 秘書として常駐させています。その延長として「ブログ執筆レーン」を組み込んだ、という位置づけです。同じく自分用エージェントを組もうとしているエンジニアの方向けに、設計方針とハマりどころを共有します。

設計方針: Skill + Sub-agent + Protocol の3層

Claude Code には役割の異なる3つの仕組みがあります。細部はバージョン依存があるため、実装時は公式ドキュメントでの確認を推奨します。

Skill: ユーザー意図を受ける入口。「ブログ」「記事書いて」などのトリガーや /blog-write [テーマ] で発火
Sub-agent: 執筆・リサーチ・品質検査を担う専任プレイヤー。ジャンル別テンプレや文体ルールを内包
Protocol: 「どの順で呼ぶか」「どこに保存するか」「どこでユーザー確認を挟むか」を定義した運用規程

構成図

ユーザー ─ "/blog-write 〇〇" ─▶ [Skill: blog-write]
                                      │
                                      ▼
                             [Main Agent (Opus)]
                  ┌───────────┬──────────────┐
                  ▼           ▼              ▼
          [research-agent][blog-writer-agent][quality-checker]
            Web調査        Sonnet            事実/論理/トーン
                           ドラフト執筆
                             │
                             ▼
       draft.md → Notion MCP → Notion DB (Draft)
               → ユーザー確認 → Live → blog.skllll.com

メインを総合判断担当（Opus）に残し、専門タスクは安価で速い Sonnet / Haiku に振るのがキモです。

ハマりポイント

1. 投稿先が Notion CMS 駆動だった

最初は「Markdown を Next.js リポに push」という素朴な想定でした。しかし実リポを調べると、記事本体は Git 上に存在せず、Notion DB がソース・オブ・トゥルースでした。ここで git ルートは無効化し、Notion MCP で DB ページを作る設計へ切り替えました。教訓は「公開インフラは想像で決めず、必ずリポジトリとビルドスクリプトを先に読む」です。

2. ジャンル分岐は `category` ではなく `Tags` で実現

コードには Post.category の参照が残っていましたが、実 DB に category は存在せず、Tags 項目（Notion の複数選択型）と status（Created / Draft / Live）で運用されていました。optional 型だったため表示は壊れていませんでしたが、エージェントがスキーマ前提で書くと即死する落とし穴です。解決は「ジャンル（tech / review / trip）は Tags に対応値を当てる」と決めるだけ。事前のタグ追加は notion-update-data-source で DDL 的に一括投入できます（ALTER COLUMN "Tags" SET MULTI_SELECT(...) 相当）。

3. Permission 境界の設計

Sub-agent にはつい親と同じ権限を渡しがちですが、執筆担当に必要なのはファイル読み書きと Web 検索まで。認証情報や Notion への直接書き込みは不要です。そこで Sub-agent の tools から破壊的操作を外し、Notion 投稿は「メインがユーザー確認を経て MCP を叩く」と決めました。主動型の Auto Mode では、このラインを先に決めないと意図しない投稿や上書きが容易に起こります。

実装のキモ

サブエージェント委譲の粒度: Sub-agent は .claude/agents/.md の frontmatter で tools と model を宣言するだけで動きます。blog-writer-agent は Sonnet、Read/Write/Glob/Grep/WebSearch/WebFetch のみ。委譲先を Opus → Sonnet / Haiku に落として役割特化させると、コストと速度を下げつつ責務が明確になります。

MCP 経由の Notion 投稿: Notion は Model Context Protocol（MCP）で接続し、notion-create-pages や notion-update-data-source を道具化。メインはドラフトを読み込み、notion-search で対象 DB を特定、notion-create-pages で status: Draft のページを作成、ユーザー確認後に notion-update-page で Live に遷移させます。ブラウザ自動化や REST API を自分で書かずに済むのが最大の利点です。

Auto Mode での主動性: ドラフトの雛形・メタ情報・タイトル案・推奨タグまで先回りで生成してくれます。ただし主動性と暴走は紙一重なので、「Draft までは自動、Live 化はユーザー明示確認」の二段構えを必ず設計に入れています。

運用してみて

最初に投下した記事は Next.js 16 + Notion API のつまずき話（約3,400字、読了6分）で、ドラフト生成から公開までおおむね10〜15分。素手で書けば2〜3時間はかかる内容なので、体感で一桁は速い印象です。品質面では quality-checker を挟むことで「それっぽいが出典がない」記述が減りました。ただし技術的な細部はバージョン依存の挙動が混じるため、必ず公式ドキュメントや Issue を当たるほうが安全です。副次的な発見として、エージェントに書かせて自分で仕上げるほうが構成の MECE が崩れにくい、というのがありました。雛形と見出しを機械側が担保してくれるので、書き手は中身の具体性と正直さに集中できます。

まとめ・次にやること

Skill + Sub-agent + Protocol の3層で、個人ブログの執筆レーンは十分に敷けます。実装の中心はプロンプト調整で、コードは MCP 接続設定程度で済みます。
ヘッドレス Notion 系 CMS では、スキーマの事実確認を執筆前の必修ステップにしてください。想定プロパティが実 DB に無いことは普通に起こります。
主動型エージェントでは、Permission 境界と「どこでユーザー確認を挟むか」を先に設計するのが重要です。