Skip to content

mamezou-tech/aidd-demo

BranchesTags

Repository files navigation

aidd-demo

Amazon Q Developer CLI + spec-kit による仕様駆動開発のデモプロジェクト

注意: このプロジェクトは講演用のデモです。本番環境での使用は想定していません。

このプロジェクトで体験できること：

  • 自然言語から仕様書を自動生成
  • 仕様から実装タスクを自動分解
  • タレントマネジメントシステム（社員検索・スキル管理）の段階的な実装
  • Spring Boot + React によるフルスタック開発

目次

前提条件

想定環境

このプロジェクトは以下の環境で動作を確認しています：

  • OS: Windows 10/11
  • WSL 2: インストール済み
    • インストール手順: wsl --install （PowerShellを管理者権限で実行）

注意: 他のOS（macOS、Linux）での動作確認は行っていません。

必須環境

Dev Container起動時に自動インストールされるもの

  • Docker Engine: Dev Container起動時、「開発コンテナーでは、Dockerを実行する必要があります。WSLにDockerをインストールしますか？」という確認ダイアログが表示されます。インストールを選択すれば自動的にインストールされます。
  • Java 17 + Gradle: Dev Container起動時に自動インストールされます。
  • Node.js 20 LTS: Dev Container起動時に自動インストールされます。
  • Amazon Q Developer CLI v1.19.7: Dev Container起動時に自動インストールされます。
  • spec-kit (specify-cli): Dev Container起動時に自動インストールされます。
  • AWS CLI: Dev Container起動時に自動インストールされます。

デモ環境構築手順

1. リポジトリの取得

以下のいずれかの方法でリポジトリを取得してください：

方法A: Fork して使う（推奨）

自分のアカウントで改変・実験したい場合：

  1. https://github.com/mamezou-tech/aidd-demo にアクセス
  2. 右上の「Fork」ボタンをクリック
  3. 自分のForkをクローン：
git clone https://github.com/<your-username>/aidd-demo
cd aidd-demo

方法B: 直接クローン（読み取り専用）

変更をプッシュしない場合：

git clone https://github.com/mamezou-tech/aidd-demo
cd aidd-demo

2. Dev Containerで開く

Visual Studio Codeで開く：

code .

コマンドパレット（Ctrl+Shift+P）から：

  • Dev Containers: Reopen in Container を選択

注意: Docker Engineがインストールされていない場合、確認ダイアログが表示されます。インストールを選択してください。

初回起動時はコンテナのビルドとツールのインストールに時間がかかります（筆者環境では30分程度）。

アプリケーションの起動

1. データベースとバックエンドの起動

Dev Container内のターミナルで：

docker compose up -d

このコマンドで以下が起動します：

  • MySQLデータベース（ポート3306）
  • Spring Bootアプリケーション（ポート8080）

確認: コンテナが起動していることを確認

docker compose ps

期待される出力: mysqldbとappコンテナのSTATUSがUp (healthy)

2. フロントエンドの起動

別のターミナルで：

cd frontend
npm run dev

注: 依存パッケージは Dev Container 起動時に自動インストールされます。

フロントエンドは http://localhost:3000 で起動します。

本番環境でのデプロイ (EC2等)

本番環境では、フロントエンドもDockerコンテナとして起動できます。

起動コマンド

docker compose --profile production up -d

このコマンドで以下がすべて起動します：

  • MySQLデータベース（ポート3306）
  • Spring Bootアプリケーション（ポート8080）
  • Reactフロントエンド（ポート3000、Nginx経由）

構成

  • フロントエンドはNginxで静的ファイルとして配信
  • /api/* へのリクエストは自動的にバックエンド（ポート8080）にプロキシ
  • ブラウザから http://<サーバーIP>:3000 でアクセス可能

注意事項

重要: ローカル開発時は --profile production を指定しないでください。

  • ローカル開発: docker compose up -d (frontendコンテナは起動しない)
  • 本番デプロイ: docker compose --profile production up -d (frontendコンテナも起動)

ローカル開発では引き続き npm run dev でVite開発サーバーを使用してください。

EC2インスタンスの作成

Q Developer CLIで以下を指示:

EC2インスタンスを作成してください。

要件:
- 名前: aidd-demo
- AMI: Amazon Linux 2023 (最新版)
- インスタンスタイプ: t3.small
- vCPU: 2
- メモリ: 2GB
- ストレージ: 20GB (gp3)
- リージョン: ap-northeast-1 (東京)
- キーペア: 新規作成して ~/.ssh/aidd-demo-key.pem に保存
- セキュリティグループ: 新規作成
  - SSH (ポート22): マイIPのみ許可
  - カスタムTCP (ポート3000): マイIPのみ許可
- パブリックIPアドレス: 自動割り当て有効

作成後、キーペアのパーミッション設定:

chmod 400 ~/.ssh/aidd-demo-key.pem

注意: t3.small (2GB RAM) を推奨。t2.micro/t3.micro (1GB) ではメモリ不足の可能性あり。

動作確認

バックエンドのヘルスチェック

curl http://localhost:8080/actuator/health

または、ブラウザで http://localhost:8080/actuator/health にアクセス

期待される結果:

{"status":"UP"}

フロントエンドへのアクセス

ブラウザで http://localhost:3000 にアクセス

ログイン情報:

主な機能

  • 社員検索: 名前、組織、役職、スキルで検索
  • 社員詳細: 社員情報とスキル一覧の表示
  • 顔写真表示: 社員の顔写真（サンプル画像）

トラブルシューティング

Dev Containerのビルドが失敗する

症状: コンテナビルド中にエラー

確認手順:

  • Docker Engineが起動しているか確認
  • WSL 2が正しくインストールされているか確認（wsl --status）
  • VS Code Dev Containers拡張機能がインストールされているか確認

対処法:

  • コマンドパレット > Dev Containers: Rebuild Container を実行
  • WSL 2が未インストールの場合: PowerShellを管理者権限で開き wsl --install を実行

Docker Engineが起動していない

症状: Cannot connect to the Docker daemon

確認手順:

docker version

対処法:

  • Docker Engineを起動
  • Windows環境でDocker Desktopを使用している場合は起動
  • WSL 2統合が有効になっているか確認（Docker Desktop > Settings > Resources > WSL Integration）

コンテナの起動が失敗する

症状: docker compose up -d でエラー

確認手順:

# ログの確認
docker compose logs

# 特定のサービスのログ
docker compose logs mysqldb
docker compose logs app

対処法:

# コンテナを停止してクリーンアップ
docker compose down -v

# 再ビルドして起動
docker compose up -d --build

アプリケーションが起動しない

症状: appコンテナがヘルスチェックに失敗

確認手順:

# アプリケーションログの確認
docker compose logs app

# MySQLの接続確認
docker compose exec mysqldb mysql -uappuser -papppass appdb -e "SELECT 1"

対処法:

  • MySQLが完全に起動するまで待つ（初回は時間がかかる場合があります）
  • docker compose restart app でアプリケーションを再起動

ポート衝突エラー

症状: port is already allocated

確認手順:

# ホストOS（Windows）で確認
netstat -ano | findstr :8080
netstat -ano | findstr :3306
netstat -ano | findstr :5173

対処法:

  • docker-compose.yml のポート設定を変更
  • または、ホストOSでポートを使用中のプロセスを終了

フロントエンドが起動しない

症状: npm run dev でエラー

確認手順:

cd frontend
npm install

対処法:

  • node_modules を削除して再インストール: rm -rf node_modules && npm install
  • バックエンドが起動しているか確認

ログインできない

症状: [email protected] / aiddTest でログインできない

確認手順:

# バックエンドのログを確認
docker compose logs app | grep "Password match"

# データベースのパスワードハッシュを確認
docker compose exec mysqldb mysql -uappuser -papppass appdb -e "SELECT email, LEFT(password_hash, 20) FROM users WHERE email='[email protected]';"

対処法:

  • データベースを再作成: docker compose down -v && docker compose up -d --build
  • パスワードハッシュが正しいか確認（$2a$10$ZoJ2Q3xPC... で始まるべき）

環境のクリーンアップ

# コンテナの停止と削除（データベースボリュームは保持）
docker compose down

# データベースボリュームも含めて完全削除
docker compose down -v

# フロントエンドのビルド成果物削除
cd frontend
rm -rf node_modules dist test-results

詳細ドキュメント

技術スタック

バックエンド

  • Java 17
  • Spring Boot 3.5.7
  • Spring Security (JWT認証)
  • Spring Data JPA
  • MySQL 8.4
  • Gradle 8.10.2
  • Testcontainers 1.20.4

フロントエンド

  • React 18
  • TypeScript 5
  • Vite 6
  • Playwright (E2Eテスト)

インフラ

  • Docker + Docker Compose V2
  • MySQL 8.4

使用しているOSS

このプロジェクトは以下のオープンソースソフトウェアを使用しています：

バックエンド

フレームワーク・ライブラリ

  • Spring Boot 3.5.7 - Apache License 2.0
    • spring-boot-starter-web
    • spring-boot-starter-security
    • spring-boot-starter-data-jpa
    • spring-boot-starter-actuator
    • spring-boot-starter-validation
  • MySQL Connector/J - GPL v2 with FOSS Exception
  • Lombok - MIT License
  • JJWT (Java JWT) 0.12.3 - Apache License 2.0

ドキュメント

  • SpringDoc OpenAPI 2.8.4 - Apache License 2.0

テスト

  • JUnit 5 - Eclipse Public License 2.0
  • Spring Security Test - Apache License 2.0
  • Testcontainers 1.20.4 - MIT License

フロントエンド

  • React 18 - MIT License
  • TypeScript 5 - Apache License 2.0
  • Vite 6 - MIT License
  • Playwright - Apache License 2.0

インフラストラクチャ

  • MySQL 8.4 - GPL v2 with FOSS Exception
  • Docker - Apache License 2.0

開発ツール

  • Amazon Q Developer CLI v1.19.7 - MIT License / Apache License 2.0（デュアルライセンス）
  • spec-kit - MIT License

詳細な依存関係は build.gradle と frontend/package.json を参照してください。

開発手法

このプロジェクトは仕様駆動開発 (Specification-Driven Development) を採用しています。

主な特徴

  1. テストファースト: すべての機能実装前にテストコードを作成
  2. 統合優先テスト: 実データベース（MySQL）を使用した統合テスト
  3. ライブラリ優先の原則: ビジネスロジックをUIから分離
  4. シンプルさのゲート: 不要な抽象化を排除

詳細は AmazonQ.md を参照してください。

ライセンス

このプロジェクトはMITライセンスの下で公開されています。 詳細は LICENSE ファイルを参照してください。

注記: このプロジェクトは講演用のデモです。本番環境での使用は想定していません。

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages