Claude Codeにフローチャート付きのリッチな仕様書を書いてもらってRunbookで共有する

こんにちは。kadoyaです。仕様書って書くの面倒ですよね。Claude Codeにコードを書いてもらうなら、仕様書も書いてもらいたいじゃないですか。マークダウンで出力してGitに保存するのもいいですが、プログラマー以外の人にもレビューしてもらえるように、それなりにいい感じの見た目にして共有したいですよね。どうせならフローチャートも書いてもらいたいです。RunbookのMCPサーバーを使って、フローチャート付きのリッチな仕様書をClaude Codeに書いてもらう方法を紹介します。AIにコードを書いてもらうときでも、まず仕様書を書いてもらうことで、ふむふむそういうアプローチで実装しようとしてるのねとプランのレビューができるのでオススメです。

Runbookとは？

Runbookはマニュアルや仕様書などの文書を共有するサービスです。作成したマニュアルをインターネットに公開することもできます。AIとの連携に力を入れており、協力なリッチエディタを備えておりながら、MCPを使ってマークダウンでの入出力ができます。手順書を作成してAIからワークフローの実行もできるとかなんとか。

RunbookのAPIトークンを取得する

Runbookは30日間無料で試用できるので、ちょっと試してみたい場合はそちらを使います。利用開始したら、こちらを参考にAPIトークンを取得します。ワークスペースのAPIトークンでも個人APIトークンでもどちらでも構いません。

https://support.runbook.jp/docs/users/19/api-token

Claude CodeにMCPサーバーをインストールする

下記コマンドでMCPサーバーをインストールします。Claude Codeを利用するディレクトリで実行する必要があります。今回はRunbookのMCPサーバーそのものの仕様書を書いてもらう（ややこしい）ため、このリポジトリの作業ディレクトリでインストールします。APIトークンとドメインは適宜置き換えてください。

https://github.com/qloba/runbook-mcp-server

claude mcp add runbook -- npx -y @runbook-docs/mcp-server --api-token=<your-api-token> --base-url=https://<your-domain>.runbook.jp

Claude Codeを起動する

ターミナルでClaude Codeを起動します。VS CodeからCloud Codeを起動している方も多いと思いますが、VS Codeと連携していると、SVG画像を生成したときに下記のエラーでClaude Codeが落ちるので今回はターミナルを使用しました。Claude CodeがVS Codeで差分を表示する際の問題のようなのでたぶんそのうち直ると思います。

node:internal/process/promises:394
    triggerUncaughtException(err, true /* fromPromise */);
    ^

まず、MCPサーバーがインストールされていることを確認します。

ちゃんとインストールされていますね！
ではさっそく仕様書を書いてもらいましょう。

プロンプトに仕様書の作成を指示する

次の手順で仕様書を作成して
コードベースからMCPサーバーの処理フローを日本語でまとめてSVGで生成する
Runbookのbook bk_xxx にSVG画像を入れた仕様書を作成する

bk_xxxの部分はあらかじめ作成しておいたブックのIDを指定します。名前を指定してもClaude CodeがMCPを使ってよしなに見つけてくれると思います。

できました！

いい感じに作成されています！ 作成した仕様書はこちらに公開しています。何も手は加えていないのですが、コードベースから正確に情報をまとめてくれています。概要図もきれいに生成されていますね。画像をクリックして拡大することもできます。

ひとつ気になったこととしては、SVG画像をClaude Codeに生成してもらったときに、一度だけInvalidなSVGが生成されたことがありました。そのときはChromeのデベロッパツールを使って画像を開くと、このように表示されたため、"&"文字が含まれていることが原因だということがわかりました。画像が表示されないよという方は参考にしてみてください。

最後に、Claude Codeとの会話ログ全文を掲載しておきます。

Claude Code会話ログ

╭───────────────────────────────────────────────────╮
│ ✻ Welcome to Claude Code!                         │
│                                                   │
│   /help for help, /status for your current setup  │
│                                                   │
│   cwd: /Users/ryo/git/runbook-mcp-server          │
╰───────────────────────────────────────────────────╯


> /mcp
  ⎿  (no content)

> 次の手順で仕様書を作成して
  コードベースからMCPサーバーの処理フローを日本語でまとめてSVGで生成する
  Runbookのbook bk_3b01k3byw8wq97z0q789sr5302 にSVG画像を入れた仕様書を作成する

⏺ MCPサーバーの処理フローを分析してSVG画像付きの仕様書を作成します。

⏺ Update Todos
  ⎿  ☐ コードベースを分析してMCPサーバーの処理フローを理解する
     ☐ 処理フローをSVG図で表現する
     ☐ 日本語でSVG画像付きの仕様書を作成する
     ☐ Runbookのbook bk_3b01k3byw8wq97z0q789sr5302 に仕様書を登録する

⏺ Update Todos
  ⎿  ☐ コードベースを分析してMCPサーバーの処理フローを理解する
     ☐ 処理フローをSVG図で表現する
     ☐ 日本語でSVG画像付きの仕様書を作成する
     ☐ Runbookのbook bk_3b01k3byw8wq97z0q789sr5302 に仕様書を登録する

⏺ Read(src/server.ts)
  ⎿  Read 144 lines (ctrl+r to expand)

⏺ Read(src/tools/tools.ts)
  ⎿  Read 680 lines (ctrl+r to expand)

⏺ Read(src/resources/resources.ts)
  ⎿  Read 99 lines (ctrl+r to expand)

⏺ Read(src/types.ts)
  ⎿  Read 232 lines (ctrl+r to expand)

⏺ List(src/queries)
  ⎿  Listed 14 paths (ctrl+r to expand)

⏺ Update Todos
  ⎿  ☒ コードベースを分析してMCPサーバーの処理フローを理解する
     ☐ 処理フローをSVG図で表現する
     ☐ 日本語でSVG画像付きの仕様書を作成する
     ☐ Runbookのbook bk_3b01k3byw8wq97z0q789sr5302 に仕様書を登録する

⏺ MCPサーバーの処理フローを詳細に分析しました。次に、分析結果を元にSVG図を作成します。

⏺ Write(mcp-server-flow.svg)
  ⎿  Wrote 221 lines to mcp-server-flow.svg
     <svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="1200" height="800" viewBox="0 0 1200 800">
       <defs>
         <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
           <polygon points="0 0, 10 3.5, 0 7" fill="#333"/>
         </marker>
         <filter id="shadow" x="-50%" y="-50%" width="200%" height="200%">
           <feDropShadow dx="2" dy="2" stdDeviation="3" flood-color="#000000" flood-opacity="0.3"/>
         </filter>
       </defs>
     … +211 lines (ctrl+r to expand)

⏺ Update Todos
  ⎿  ☒ コードベースを分析してMCPサーバーの処理フローを理解する
     ☒ 処理フローをSVG図で表現する
     ☐ 日本語でSVG画像付きの仕様書を作成する
     ☐ Runbookのbook bk_3b01k3byw8wq97z0q789sr5302 に仕様書を登録する

⏺ Read(mcp-server-flow.svg)
  ⎿  Read 221 lines (ctrl+r to expand)

⏺ SVGファイルをDataURIエンコード形式に変換して、Runbook記事に埋め込める形式にします。

⏺ Update Todos
  ⎿  ☒ コードベースを分析してMCPサーバーの処理フローを理解する
     ☒ 処理フローをSVG図で表現する
     ☒ 日本語でSVG画像付きの仕様書を作成する
     ☒ Runbookのbook bk_3b01k3byw8wq97z0q789sr5302 に仕様書を登録する

⏺ 完了しました！MCPサーバーの処理フローを日本語でまとめたSVG画像付きの仕様書を作成し、Runbookのbook bk_3b01k3byw8wq97z0q789sr5302 に登録しました。

  仕様書の内容：
  - MCPサーバーの全体的な処理フロー図（SVG形式）
  - システム構成の詳細説明
  - 提供するツール・リソースの一覧
  - GraphQLクエリの説明
  - 基本処理フローとワークフロー処理フローの解説
  - 技術仕様の詳細

  記事は以下のURLで確認できます：

Claude CodeとRunbookのMCPを使うと仕様書の作成とレビューがはかどります。ぜひ試してみてください！