「ドキュメントもAIフレンドリーに」というテーマで、今日はUML仕様書の作り方を一新しました。キーワードは「Mermaid（マーメイド）」です。
📄 ドキュメントはMarkdownで書く、というこだわり
弊社ではドキュメントをなるべくMarkdown形式で書くようにしています。理由はシンプルで、WordのdocxファイルやPDFはテキストとして読み込みにくく、AIとの相性が良くないからです。MarkdownならプレーンテキストなのでそのままAIに読み込ませることができる。この点は開発を進めるうえで地味に大きなポイントです。
ただ、Markdownでひとつ困るのが「図」の扱いです。フローチャートやクラス図などを表現しようとすると、JPEGやPNGのビットマップ画像、あるいはSVGのベクター形式で書くのが一般的ですが、これらはどちらも画像ファイルなのでAIがテキストとして読めない。「図だけ読めません」では困ります。
🧜 そこでMermaidの登場
そこで注目したのが「Mermaid（マーメイド）」という記法です。フローチャート・クラス図・シーケンス図などをテキストで記述できる形式で、Markdownの中にそのまま埋め込めます。つまり、図もドキュメントも全部テキストで管理できるというわけです。
VS Code（Visual Studio Code）にMermaidのプレビュープラグインを入れれば、Markdownファイルを開いたままリアルタイムで図の仕上がりを確認できます。書いて、見て、直して、がスムーズにできる環境が整いました。
📐 作ったのはサーマルマップロガーのUML仕様書
今回AIに作ってもらったのは、サーマルマップロガーのUML仕様書です。内容は盛りだくさんで、以下の章立てで構成されています。
- 第1章 システム概要・ハードウェア構成：ESP32・AMG8833センサー・SDカード・スマホブラウザの接続関係をフローチャートで図示
- 第2章 ユースケース図：スマホブラウザとESP32システムがやりとりする機能一覧（データ取得・記録開始停止・ファイル削除など）
- 第3章 クラス図：AppState・SensorModule・StorageModule・NetworkModuleの4つのコンポーネントと依存関係
- 第4章 シーケンス図：起動フェーズとリアルタイム表示フェーズの処理の流れ
- 第5章 アクティビティ図：温度データ取得から配信までの処理ロジック
- 第6章 コンポーネント図：ライブラリ・ハードウェア間の依存構造
- 第7章 HTTP APIエンドポイント仕様：7本のAPIの役割を表形式で整理
仕様書はGitHubで公開しています：specification.md
💡 仕様書の中にも「課題」が見える
面白いのは、この仕様書の中に先日Claudeがレビューで指摘した問題点もそのまま注記として残してある点です。たとえばクラス図の横には「SDカードのopenとcloseを毎回実行している」「toggle失敗時のフラグ未処理」といったコメントが添えられています。仕様書が設計図であると同時に、改善タスクリストにもなっているわけです。
「テキストで書けるものは全部テキストで」という地味なこだわりが、AI活用の効率を着実に上げていっている気がします。Mermaid、なかなかいいですよ。
コメント