メインコンテンツへ移動
AIチュートリアル

SoftJL Community 入門チュートリアル：AIで要件・UML・テスト・仕様書をつなぐ

本記事では、SoftJL Communityの導入方法とOpenAI互換モデルの設定方法を解説します。図書館の座席予約システムを例に、要件確認、実現可能性分析、UMLモデリング、テストカバレッジの確認、エンジニアリング仕様書の生成までを行います。

約17分で読了
SoftJL Community 入門：AIで要件・UML・テスト・仕様書をつなぐ

SoftJL Communityとは

SoftJL Communityは、ソフトウェア系の卒業設計、授業設計、UML課題向けに独自運用できるAIソフトウェアエンジニアリングワークベンチです。要件分析、実現可能性分析、UMLモデリング、設計、テスト、エンジニアリング文書、変更追跡をつなぎ、要件が設計とテストに反映されているかを確認し、修正、発表、答弁に必要な追跡可能な根拠を整理できます。

コミュニティ版は完全なソースコードを提供し、Apache License 2.0でライセンスされています。公式ホスティング版と比較すると、コミュニティ版ではサービス、データベース、モデルプロバイダーを自分で管理する必要がありますが、要件ルール抽出、完全な要件・設計モデル、テストカバレッジ、説明書生成、ソース追跡、プロジェクト管理、BYOKモデル接続などの主要機能は維持されています。

公式サイトのホームページ — デスクトップのファーストビュー

コアワークフロー

このプラットフォームは、要件から検証までのエンジニアリングチェーンを中心に動作します。まず要件を入力してルールを確認し、次に実現可能性を分析して要件モデルと設計モデルを生成します。その後、テストケースとカバレッジマトリクスを生成し、最後に編集・ダウンロード可能なエンジニアリング説明書を作成します。

  • 要件ルール：自然言語の要件からルールを抽出し、品質チェック、修正、手動確認、受け入れ条件の整理を行います。
  • 実現可能性分析：システム環境図、業務・システムフロー図、実装方式の分析を生成します。
  • UMLモデル：機能構造、ユースケース、ドメイン概念、プロトタイプ画面、配置要件、全体アーキテクチャ、設計クラス、データベースなどのモデルを構築します。
  • テストとカバレッジ：正常系、異常系、境界条件のテストケースを生成し、カバレッジマトリクスとトレーサビリティマトリクスで不足箇所を特定します。
  • エンジニアリング文書：実現可能性調査報告書、要件仕様書、ソフトウェア設計説明書を生成し、バージョン管理とDOCXダウンロードに対応します。
  • 変更影響：要件、設計、テスト、説明書間のソース関係を確認し、変更後にどの成果物を更新する必要があるか判断します。
  • モデル接続：OpenAI互換のモデルサービスを設定し、自分のモデルプロバイダーを呼び出します。
生成結果はエンジニアリング上の根拠を特定・整理するために使用します。モデルの制約、図表の内容、説明書と業務内容の整合性は引き続き人手で確認し、実際のシステムでテストを実行する必要があります。

インストール前の環境準備

初回実行には、次の環境を準備する必要があります。

  • Node.js 22
  • npm 10
  • Java 21
  • Graphviz
  • 任意：PostgreSQLとOnlyOfficeの実行に使用するDocker

初めてレンダリングサービスを使用するとき、システムがPDF用の中国語フォントをオンラインでダウンロードする場合があります。Dockerはコアサービスを一時的に試すだけなら必須ではありませんが、長期利用では永続化されたPostgreSQLの設定を推奨します。DOCXをオンライン編集する場合は、OnlyOfficeも有効にする必要があります。

コアサービスをすぐに起動する

1. ソースコードを取得して依存関係をインストールする

git clone https://github.com/guolola/SoftJL.git
cd SoftJL
npm ci

2. 開発環境を起動する

npm run dev

このコマンドはcontractsとpromptsの共有パッケージを自動的にビルドし、Web、API、レンダリングサービスを並行して起動します。Webは通常http://localhost:3000で動作し、APIはポート4101、Render Serviceはポート4002を使用します。

Webの出力にReadyと表示されたら、http://localhost:3000を開けます。同時に、ヘルス状態を確認することを推奨します。

http://localhost:3000/api/health
http://127.0.0.1:4002/health

2つのヘルスチェックインターフェースは、いずれもstatus: "ok"を含む結果を返す必要があります。

3. 一時メモリモードを理解する

npm run devを直接実行すると、デフォルトでは一時メモリモードが使用されます。サービスを再起動すると、アカウント、プロジェクト、モデルサービス設定、実行履歴が失われます。文書ファイルはローカルディレクトリに個別に保存されますが、データベースのバックアップの代わりにはなりません。そのため、このモードは簡単な体験には適していますが、プロジェクトの長期保存には適していません。

永続化データベースとオンライン編集を設定する

開発用PostgreSQLを使用する

公式サイトのホームページ — デスクトップのファーストビュー

ローカルマシンにDockerをインストールして起動した後、次のコマンドで専用の開発用データベースとコアサービスを実行できます。

npm run dev:postgres

この方法では、データベースがDockerデータボリュームに保存されます。スクリプト内のデータベース認証情報はローカル開発専用です。実稼働環境では必ず置き換え、既存の完全版データベースをコミュニティ版データベースとして直接使用しないでください。

既存のPostgreSQLに接続する

PostgreSQLをすでに用意している場合は、ルートディレクトリの.env.exampleを.envにコピーし、DATABASE_URLと自分で生成したUML_PROVIDER_CONFIG_SECRETを設定します。

cp .env.example .env

設定後、npm run devを再度実行します。暗号化キーは適切に保管してください。UML_PROVIDER_CONFIG_SECRETを不用意に変更すると、保存済みのモデルプロバイダー認証情報を復号できなくなります。データベース接続情報とキーもGitにコミットしないでください。

OnlyOfficeを有効にする

説明書をオンライン編集する必要がある場合は、まずDockerエンジンを起動してから、次を実行します。

npm run dev:full

このスクリプトはローカルマシンの8080ポートにあるOnlyOfficeを確認します。サービスが利用できない場合は、対応するコンテナを作成または起動します。初回実行時にはイメージのダウンロードが必要になる場合があります。コアサービスだけでも文書の生成とダウンロードは可能ですが、オンライン編集機能にはOnlyOfficeの追加設定が必要です。

AIモデルサービスを設定する

  1. Webサービスを起動してアカウントにログインします。
  2. アカウント設定に移動し、OpenAI互換のProviderを追加します。
  3. モデルプロバイダーのHTTPS Base URLとAPI Keyを入力します。
  4. モデルの検出と接続テストを実行します。
  5. 利用可能なモデルを1つ選び、デフォルトモデルに設定します。

自前でデプロイした環境では、自分のモデルサービスを使用します。モデル呼び出しの費用は、対応するプロバイダーに支払います。実稼働環境では永続化データベースと認証情報の暗号化キーを使用し、開発用ゲストアクセスとlegacy平文フォールバック入口を無効にしてください。

図書館の座席予約システムでモデリングを行う

ここでは、次のような簡単な要件を例にします。学生はログイン後に空席を検索し、日付と時間帯を選択して予約を申請します。同じ学生は同じ時間帯に重複して予約できません。予約が成功すると通知が送信され、管理者は座席の管理、予約記録の確認、異常なキャンセルの処理を行えます。

ステップ1：プロジェクトを作成して要件ルールを確認する

プロジェクトを作成したら、上記の業務説明をプラットフォームに入力し、システムに要件ルールを抽出させます。ユーザーロール、予約条件、重複予約の制約、通知動作、異常キャンセルのフローを重点的に確認します。問題がなければルールと受け入れ条件を保存し、曖昧な要件に基づいて後続のモデルが構築されるのを防ぎます。

ステップ2：実現可能性分析を完了する

プロジェクトのフローに従って、次の3項目を分析します。

  • システム環境図：学生、管理者、通知サービス、予約システム間の境界と相互作用を明確にします。
  • 業務・システムフロー図：座席検索、予約申請、通知送信、異常キャンセルの処理フローを整理します。
  • 実装方式：候補方式を比較し、コスト、メリット、リスクを記録します。

分析完了後、まずシステム境界とフローが元の要件に適合しているか確認してから、モデル生成の段階に進みます。

ステップ3：要件モデルと設計モデルを生成する

確認済みの要件に基づいて、機能構造、全体業務フロー、ユースケース、ドメイン概念、プロトタイプ画面の関係、配置要件などを含む完全な要件モデルを生成できます。要件モデルを確認した後、前提関係に従って全体アーキテクチャ、ユースケース実現、設計クラス、ページナビゲーション、データベース、コンポーネント関係、配置設計などの設計モデルを生成します。

ダッシュボードの統計と成果物生成時間

生成後にソース関係を開き、各設計要素が要件ルールまで遡れるか確認します。これにより、予約ルールが変更されたとき、影響を受けるユースケース、クラス、データベース設計、テストを容易に特定できます。

ステップ4：テストとカバレッジマトリクスを生成する

予約システムについて、少なくとも次のシナリオを確認します。

  • 学生が指定した日付と時間帯の空席を検索できる。
  • 学生が有効な予約を申請し、通知を受け取れる。
  • 同じ学生が同じ時間帯に重複予約した場合、システムがリクエストを拒否できる。
  • 空席がない、時間帯が不正、予約情報が不足している場合、システムが異常を処理できる。
  • 管理者が座席を管理し、予約記録を確認し、異常なキャンセルを処理できる。

カバレッジマトリクスとトレーサビリティマトリクスを使用して、設計上またはテスト上の根拠がない要件を特定します。プラットフォームが生成したテストケースは、実際のシステムで実行する必要があります。生成に成功したことだけを受け入れ結果として扱うことはできません。

ステップ5：エンジニアリング説明書を生成する

実現可能性分析、要件モデル、設計モデルが完了したら、実現可能性調査報告書、要件仕様書、ソフトウェア設計説明書の3種類のエンジニアリング文書を生成できます。生成後、本文と図表が一致しているか確認し、学校のテンプレートと書式要件に従って修正してから、バージョン管理とDOCXダウンロードを行います。

ダッシュボードの統計と成果物生成時間

要件変更時の対応方法

たとえば、プロジェクトのルールを「同じ学生は同じ時間帯に重複予約できない」から「同じ学生は1日に最大2つの時間帯を予約できる」に変更するとします。説明書の1文だけを変更せず、ソースと依存関係に沿って次を確認してください。

  1. 新しい要件ルールを保存して確認します。
  2. ソース関係と変更影響を開き、影響を受ける要件、ユースケース、設計、テスト成果物を確認します。
  3. 依存順序に従って要件モデルと設計モデルを更新します。
  4. データベース制約、業務フロー、異常処理を再確認します。
  5. テストケースとカバレッジマトリクスを更新し、実際のシステムで回帰テストを実行します。
  6. 関連する説明書を再生成または修正し、バージョン記録を保持します。

ソースの連結線とカバレッジ数は確認範囲の特定に役立ちますが、最終的には具体的なモデルを開き、制約、入力条件、動作が完全かどうか確認する必要があります。

外部Coding Agentに接続する

コミュニティ版では、デプロイ担当者が読み取り専用のMCP接続を自分で有効にできます。互換性のあるCoding Agentは、プロジェクト範囲内に保存された設計、受け入れ条件、エンジニアリング制約、テスト情報を読み取れます。MCPのローカル体験入口はサイドバーの「プログラミングアシスタント」またはプロジェクト設定の「このプロジェクトに接続」です。使用前にインストールとビルドを完了する必要があります。

npm run dev:mcp

この接続はエンジニアリング上の根拠を読み取り専用で提供するものであり、コードレビュー、実際の実行、テスト受け入れに代わるものではありません。READMEにも、実際のCoding Agentクライアントとの互換性と生成コードの受け入れ確認は引き続き改善中であると明記されています。利用時はMCP接続ガイドを参照してください。

よく使う開発コマンド

  • npm run build:packages：contractsとpromptsの共有パッケージをビルドします。
  • npm run build：共有パッケージとすべてのアプリケーションをビルドします。
  • npm run dev:render：PlantUMLレンダリングサービスのみを起動します。
  • npm run test:contracts：共有コントラクトを検証します。
  • npm run test:api：APIテストを実行します。
  • npm run test:render：レンダリングサービスのテストを実行します。
  • npm run test:web：完全なWebテストを実行します。
  • npm run typecheck:web：Webの型をチェックします。
  • npm run lint:web：Webの静的チェックを実行します。
  • npm audit --audit-level=high：依存関係のセキュリティ公告を確認します。

共有パッケージに変更があった場合、アプリケーションを単独で起動したりテストを実行したりする前に、npm run build:packagesを実行してください。ビルド出力、環境設定、秘密鍵、ログ、ローカル実行データはGitの無視対象に保持する必要があります。

アーキテクチャ概要

プロジェクトは複数アプリケーションと共有パッケージによる構成を採用しています。

  • apps/web：React、Next.jsのワークスペースとページ。
  • apps/api：Fastify API、認証、生成パイプライン、実行記録、ドキュメント組み立て。
  • apps/render-service：PlantUML図のレンダリング。
  • packages/contractsとpackages/prompts：共有コントラクトと生成プロンプト。
  • packages/harness-e2eとpackages/harness-eval：受け入れテストと品質評価。

デプロイと利用に関する注意事項

  • コミュニティ版では独立したデータベースを使用し、公式サイトの完全版データベースの縮小代替として使用しないでください。
  • 開発用起動スクリプトのデータベース認証情報はローカル環境での使用に限り適しており、本番環境では必ず変更してください。
  • モデルキー、データベース接続情報、暗号化キーをコードリポジトリにコミットしてはいけません。
  • プロジェクト設計書はプロジェクト報告書の資料として利用できますが、完全な卒業論文に相当するものではありません。
  • 図表、設計書、コードの業務上の整合性は手作業で確認し、実行結果の証拠によって検証する必要があります。
  • 本番デプロイ前に、サービスドメイン、データベース、メール、モデルの設定を置き換えてください。

まとめ

SoftJL Communityは、卒業制作や授業課題をエンジニアリングの手順に沿って整理したい開発者に適しています。環境のインストール、データベース、モデルの設定を完了すると、要件ルールを起点に、実現可能性分析、UML要件・設計モデル、テストカバレッジ、プロジェクト設計書を段階的に生成し、要件変更時の影響範囲を追跡できます。

資料の分散や重複した整理作業を減らせますが、設計上の判断、コード実装、実際のテスト、最終発表の準備に代わるものではありません。プラットフォームが生成した内容を、追跡可能なエンジニアリング草稿および確認資料として活用し、学校の要件と実際のシステム実行結果を組み合わせて最終成果物を完成させることを推奨します。