内部仕様を可視化して ドキュメント品質を上げる - 「読む仕様書」から「観る仕様書」へ -

Mermaid で書いた機能仕様書を AI に読ませ、内部処理を「動く図」にして抜け・誤りを見つける試み

動画: https://youtu.be/uIeH8T9d9ZU?si=CZqELE74CS1ZBAGl

Transcript

1. © コロッケそば 2026 All rights reserved. 内部仕様を可視化して ドキュメント品質を上げる - 「読む仕様書」から「観る仕様書」へ - Mermaid で書いた機能仕様書を AI に読ませ、内部処理を「動く図」にして 抜け・誤りを見つける試み 外部API Agent（身体） LLM（脳） soul.md（人格） skills（知識） 人間 1
2. © コロッケそば 2026 All rights reserved. 課 題 なぜ「内部仕様」を可視化するのか 仕様書は静的 表・文章・図は「読む」もの。処理が時間とともにどう動くかは見 えない。 抜け・ズレが起きる 記載漏れ・誤り・認識のズレに、静的なレビューでは気づきにくい。 頭の中の設計が消える 「こう動くはず」と考えた内部ロジックが、本当に全部書けている か確認できない。 静的ドキュメント ? 動いている“流れ”が見えない 2
3. © コロッケそば 2026 All rights reserved. 目 的 内部処理を可視化して、品質を上げる 内部処理を可視化した結果を見ながら、ドキュメントに 「記載漏れ・誤り」 がないかを チェックし、考えた内部機能がすべて記載されているか を確かめて、ドキュメント品質を高める。 記載漏れはないか 可視化で初めて気づく「書き忘れた処理・ 分岐・状態」を洗い出す。 記載は正しいか 図にすると、文章では曖昧だった条件や順 序の誤りが浮かび上がる。 全部載っているか 頭の中で設計した内部機能が、漏れなく 仕様書に反映されているか照合する。 3
4. © コロッケそば 2026 All rights reserved. ア イ デ ア 静的ドキュメント → 動く可視化 B E F O R E 仕様書を「読む」 表・文章・Mermaid 図が並ぶ 処理の順序や分岐は頭の中で補完 「動き」は想像するしかない 抜けや誤りはレビュー頼み AIで 変換 A F T E R 内部ロジックを「観る」 1ステップずつ処理を再生 データが各部品をどう流れるか可視化 LLM・ツール・人間の振る舞いが見える 見た瞬間に抜け・誤りに気づける 4
5. © コロッケそば 2026 All rights reserved. 効 果 期待する 3 つの効果 01 実装不足を防ぐ 成果物プログラムに必要な処理・分岐の 作り込み漏れを、可視化の段階で発見で きる。 02 テストを効率化 状態遷移や分岐が見えるので、必要なテ ストケースを的確かつ効率よく洗い出せ る。 03 外注品質を確保 社外発注時、静的仕様＋動く可視化で受 注側の理解が進み、結果として品質が上 がる。 5
6. © コロッケそば 2026 All rights reserved. 手 順 試行はたった 2 ステップ S T E P 1 Markdown（Mermaid）で 機能仕様書を書く 構成図・シーケンス図・状態遷移を Mermaid で記述。 表や設定値も含め、人もAIも読める一次資料にする。 S T E P 2 AI（Claude など）に読ませて 可視化アプリを生成する 仕様書を渡すだけで、内部処理を1ステップずつ再生する HTML アプリが出力される。外部仕様ではなく内部ロジックの 動きを可視化。 ポイント：特別なツールは不要。Markdown 仕様書さえあれば、誰でも同じ手順で内部ロジックビューアを作れる。 6
7. © コロッケそば 2026 All rights reserved. 題 材 例：見守りエージェント「コロッケそば」 名古屋の気温を1時間ごとに自律監視し、意味のある変化のときだけ AI が判断 して ロボホン／LINE に通知。送信前に 人間が承 認・編集・却下 でき、その結果から 自己学習 する見守りエージェント。 soul.md skills/ 外部API Open-Meteo エージェント 脳=ローカルLLM 人間 承認/編集/却下 通知先 ロボホン/LINE AI が要否を判断 外部API Agent（身体） LLM（脳） soul.md（人格） skills（知識） 人間 7
8. © コロッケそば 2026 All rights reserved. 可 視 化 例 ① データフロー・マップ：いま“どこ”が動くか 各部品を色で分類 外部API・Agent・LLM・人格・知識・人 間を色分けし、一目で役割が分かる。 動作中が光る いま処理している部品がハイライト。処理 の「現在地」が常に見える。 線＝データの通り道 部品を結ぶ線の上を、実際のデータがパケ ットとして流れる。 8
9. © コロッケそば 2026 All rights reserved. 可 視 化 例 ② 内部データの“流れ”まで見える UIを見せるだけでなく、関数の 引数→戻り値 と、それが LLM の会話履歴に積み上がる様子まで観える。 ツール I/O（関数の入出力） 戻り値が コンテキストへ 積まれる LLM コンテキスト（会話履歴の蓄積） 9
10. © コロッケそば 2026 All rights reserved. シ ー ケ ン ス 図 1 回の監視サイクル（info 通知） 監視ループ LLM（脳） Open-Meteo 人間 HiTL 通知先 ① 定期チェック実行（tools 付き） ② fetch_weather ③ 気温/湿度/天気コード ④ check_alert（前回との差を判定） ⑤ notify → Point B 承認待ち ⑥ 承認/編集（120秒で自動承認） ⑦ 発話 + Flex Message を並列送信 ⑧ 最終返答 → データ保存・次の待 機へ 点線＝応答／実線＝呼び出し。閾値超過の場合は ⑤ の前に Point A（送信可否）が入る。 10
11. © コロッケそば 2026 All rights reserved. 可 視 化 例 ③ 人間が止められる（Human-in-the-Loop） 送信前に割り込む alert 通知は送信の直前に停止。人間が「 送る/送らない」を判断する（Point A）。 誤通知を実害前に止める 誤った通知は人が却下。自動化に安全弁を 入れられる。 仕様の介入点が見える 仕様書の HiTL Point A / B が「いつ・ど う」割り込むか、動きで確認できる。 11
12. © コロッケそば 2026 All rights reserved. 可 視 化 例 ④ 学んで賢くなる（自己進化） 人間の編集・却下が教師データになり、新しい skill が追加・更新される（NEW / UPDATED）。 学習のループ 人間が文面を編集／却下 LLM が学び <update_skill> を出力 skills/*.md に保存 次サイクルで読み直し、判断が改善 12
13. © コロッケそば 2026 All rights reserved. S U M M A R Y 可視化が、ドキュメント品質を上げる 抜け・誤りに気づける 内部処理を“動く図”にすると、静的レビュ ーでは見えなかった漏れ・誤りが浮かぶ。 仕様＝静的＋動き 表や文章に加え、内部ロジックの動きを併 せ持つことで仕様の解像度が上がる。 2ステップで誰でも Mermaid仕様書 → AIで可視化。特別な道 具なしに、今日から試せる。 「読む仕様書」から「観る仕様書」へ。 以上 13