ジェンスパーク(Genspark)開発で不具合だらけ？UML設計図で整合性確認する実践テクニック

📋 目次

はじめに：複雑化したシステムの落とし穴

ジェンスパーク(Genspark)でWebアプリケーションを開発していると、最初はシンプルだったシステムが、機能追加や修正を重ねるうちにどんどん複雑になっていきます。そして気づいたときには、「あれ、仕様書に書いてあることと実装が違う…」という事態に陥っていることがあります。

このブログ「ジェンスパーク(Genspark)開発奮闘記」でも、実は大きな問題に直面していました。データベースに存在するカラムが仕様書に記載されていなかったり、API仕様が曖昧だったり、システム全体の整合性が取れなくなっていたのです。

システムが複雑になると、仕様書を作っただけでは不具合が入り込む余地が大きくなります。AIエージェントに仕様書と実装を見比べさせても、両方全てをチェックできるわけではないようで、漏れが出てきます。

仕様書と実装のズレが見えない問題

AIに直接比較させても見つからない理由

ジェンスパーク(Genspark)のようなAIツールは非常に強力ですが、複雑なシステムの仕様書と実装コードを同時に比較させようとすると、以下のような問題が発生します：

  • コンテキストウィンドウの限界：大量のコードと長い仕様書を同時に処理しきれない
  • 情報の複雑さ：どこに注目すべきか優先順位がつけにくい
  • 見落としの発生：細かい差異を見逃してしまう
  • 確認漏れ：チェックすべき項目を網羅しきれない

実際に起きた問題の例

  • データベースにview_countカラムが存在するのに、仕様書には記載なし
  • NULL制約の仕様が実装と異なる
  • Cloudflare Pages Functions APIの仕様が不明確
  • Reactコンポーネント構造が文書化されていない

UML設計図を使った整合性確認とは

そんなとき有効なのが、UML設計図を使った整合性確認です。UML（Unified Modeling Language）は、ソフトウェアシステムを図で表現できる標準的な記法です。

基本的なアプローチ

ポイントは、仕様書からUMLを作るのではなく、実装からUMLを作らせる点です。この方がAIには整合性の確認がしやすいようです。

💡 なぜ「実装→UML」なのか？

実装コードは動いている事実そのものです。コードからUMLに変換する際は、構造をそのまま図示するだけなので間違いが少なくなります。一方、仕様書から作ると、AIの解釈が入り込む余地があり、不正確になる可能性があります。

整合性確認の流れ

  1. 実装コードからUML設計図を作成（AI支援）
  2. UML設計図と仕様書を比較（AI支援）
  3. 差異を抽出して問題点を明確化
  4. 修正すべき箇所を特定して対応

なぜUMLが効果的なのか

1. 視覚的に理解しやすい

UMLは図で表現されるため、システムの構造や関係性が一目でわかります。長い文章の仕様書よりも、全体像を把握しやすくなります。

2. 標準化された表現

UMLは国際的に標準化された記法なので、表現の曖昧さが減ります。データベースならER図、処理の流れならシーケンス図というように、用途に応じて最適な図を使い分けられます。

3. 中間表現として機能

実装コードは詳細すぎて全体像が見えにくく、仕様書は抽象的すぎて具体性に欠けることがあります。UMLはその中間に位置し、適度な抽象度で情報を整理できます。

UMLの種類と用途

UML図の種類 用途 確認できる内容
ER図 データベース構造 テーブル、カラム、リレーション、制約
クラス図 コード構造 クラス、メソッド、依存関係
シーケンス図 処理の流れ API呼び出し順序、タイミング
アーキテクチャ図 システム全体構成 コンポーネント間の関係、データフロー

4. 人間も確認できる

UMLはソースコードを人間が理解するための設計図なので、AIだけでなく、開発者自身が目視でチェックすることも可能です。これにより、AIが見落とした問題も発見しやすくなります。

実践事例：7つの不具合を発見した話

このブログシステムでは、2025年12月15日に実装からUML設計図を作成し、仕様書との差異を徹底的に洗い出しました。その結果、7つの重大な不具合を発見・修正することができました。

発見された問題（優先度別）

🔴 高優先度（必須修正）

1. view_countカラムが仕様書に記載なし
データベースには閲覧数を記録するview_countカラムが存在するのに、仕様書には一切記載されていませんでした。これでは新規開発者がシステムを理解できません。

修正内容

修正前：

CREATE TABLE blog_posts ( ... is_published INTEGER DEFAULT 0, published_at TEXT, created_at TEXT DEFAULT CURRENT_TIMESTAMP );

修正後：

CREATE TABLE blog_posts ( ... is_published INTEGER DEFAULT 0, view_count INTEGER DEFAULT 0, -- ← 追加 created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP );
2. NOT NULL制約が実装と不一致
実装では6つのカラムにNOT NULL制約が設定されているのに、仕様書では制約の記載が漏れていました。これはデータの整合性に関わる重要な情報です。
3. Cloudflare Pages Functions API仕様が不明
実装には記事取得APIやRSSフィードAPIが存在するのに、仕様書にはエンドポイント、パラメータ、レスポンス形式などの情報が一切ありませんでした。

🟡 中優先度（推奨修正）

4. Reactコンポーネント構造が不明
フロントエンドの構成（ページ、コンポーネント、使用技術）が文書化されていませんでした。これを明記することで、UI修正時の参照が容易になります。
5. 記事ID範囲が曖昧
「記事ID範囲: 103〜111」とだけ記載されており、初期データと追加データの区別がつきませんでした。「104〜112（初期: 104-108、追加: 109-112）」と詳細化しました。

🟢 低優先度（任意）

  • 6. GitHub Actionsのpushトリガー記載漏れ
  • 7. アーキテクチャ図のデータベース注釈不足

✨ 修正の成果

これらの問題を全て修正した結果、以下の効果が得られました：

  • ✅ データベーススキーマが実装と完全一致
  • ✅ APIの仕様が明確（エンドポイント、パラメータ、レスポンス）
  • ✅ フロントエンド構成が明確（ページ、コンポーネント、技術スタック）
  • ✅ 新規開発者がシステムを正確に理解可能
  • ✅ メンテナンス性が大幅に向上

具体的な実践手順

では、実際にUML設計図を使った整合性確認をどのように進めればよいのか、ステップバイステップで解説します。

ステップ1：実装からUML設計図を作成する

まず、ジェンスパーク(Genspark)に実装コードを見せて、UML設計図を作成してもらいます。このとき、PlantUML形式で出力してもらうと、テキストベースで管理しやすく、バージョン管理も容易です。

ジェンスパーク(Genspark)への指示例

「このデータベーススキーマファイルを見て、ER図をPlantUML形式で作成してください。すべてのテーブル、カラム、制約、インデックスを含めてください。」

「このReactプロジェクトのソースコードを見て、コンポーネント構造をクラス図として作成してください。」

ステップ2：作成したUMLを確認・修正する

AIが作成したUML設計図は、そのまま使えることもあれば、細かい調整が必要な場合もあります。PlantUML Online Serverなどで図を表示して、内容を確認しましょう。

💡 確認ポイント

  • すべての重要な要素が含まれているか
  • 関係性が正確に表現されているか
  • 見やすく整理されているか

ステップ3：UMLと仕様書を比較させる

次に、完成したUML設計図と仕様書をジェンスパーク(Genspark)に見せて、差異を抽出してもらいます。

ジェンスパーク(Genspark)への指示例

「このER図と仕様書のデータベース仕様を比較して、以下の観点で差異をリストアップしてください：

  • 仕様書に記載がないが実装に存在する要素
  • 仕様書と実装で定義が異なる要素
  • 制約やデフォルト値の違い

差異は優先度（高・中・低）をつけて整理してください。」

ステップ4：差異を修正する

抽出された差異を確認し、優先度の高いものから修正していきます。通常は、仕様書を実装に合わせて修正することが多くなります（実装が正しい前提）。

⚠️ 注意：実装が間違っている場合

もし実装側に明らかなバグがある場合は、実装を修正する必要があります。UMLと仕様書の比較により、「そもそも実装が間違っていた」というケースも発見できます。

ステップ5：UML設計図も保存・管理する

修正が完了したら、作成したUML設計図もプロジェクトの一部として保存・管理しましょう。今後のメンテナンスや新機能追加の際に、非常に役立ちます。

推奨される管理方法

  • GitHubリポジトリのdocs/uml/フォルダに保存
  • PlantUML形式（.puml）でテキスト管理
  • README.mdにUMLの説明と表示方法を記載
  • システム変更時はUMLも同時に更新

成功のポイント

1. 最初は小さく始める

いきなりシステム全体のUMLを作ろうとすると大変です。まずは問題が起きている部分（データベース、特定のAPIなど）から始めましょう。

2. 実装→UMLの順序を守る

繰り返しになりますが、実装からUMLを作ることが重要です。仕様書からUMLを作ると、仕様書の曖昧さや誤りがそのまま反映されてしまいます。

実装コードは「動いている事実」です。そこから図を作ることで、現実のシステムを正確に把握できます。

3. 複数の視点で確認する

1種類のUML図だけでなく、複数の視点から確認すると効果的です：

  • ER図でデータ構造を確認
  • シーケンス図で処理フローを確認
  • クラス図でコード構造を確認
  • アーキテクチャ図でシステム全体を確認

4. 人間の目でも確認する

AIが作成したUML設計図は、最終的に人間の目でも確認しましょう。図を見て「何か違和感がある」と感じたら、それが重要な発見につながることもあります。

5. 定期的にメンテナンスする

システムは常に変化します。大きな機能追加や修正を行ったら、UML設計図も更新しましょう。それを仕様書と比較することで、常に整合性を保てます。

まとめ

ジェンスパーク(Genspark)開発でシステムが複雑化してきたら、UML設計図を使った整合性確認が非常に効果的です。

✅ この記事の重要ポイント

  • 複雑なシステムでは、仕様書と実装のズレが見えにくくなる
  • AIに直接比較させるだけでは、重要な差異を見落とす可能性がある
  • 実装からUMLを作成し、それを仕様書と比較するのが効果的
  • UMLは視覚的で標準化されており、適度な抽象度で情報を整理できる
  • 実践事例では7つの重大な不具合を発見・修正できた
  • 人間も確認できる図なので、AIが見落とした問題も発見しやすい
ジェンスパーク(Genspark)開発で不具合だらけになってしまったら、UML設計図を使った整合性確認をすることをおすすめします。実装の真実を図で可視化し、仕様書との差異を明確にすることで、システムの品質を大幅に向上させることができます。

関連記事

参考リンク

この記事が参考になったら、ぜひSNSでシェアしてください！
ジェンスパーク(Genspark)開発の知見を共有し、より良い開発体験を広めていきましょう。