App 基盤構築スキル

このスキルは新規 App の初期骨架を自動生成します。

構築フロー（標準手順）

フェーズ 1: 基盤做成（Foundation）

1. 要件確認

   • アプリ名（snake_case）
   • 表示タイトル
   • 説明文
   • DB 名
   • Redis 必要可否
   • 履歴 DB 必要可否

2. テンプレート適用

   # agentflow CLI でテンプレート生成
   python -m agentflow.cli new-app \
     --template fullstack-app \
     --name my_app \
     --title "My Application" \
     --output apps/my_app

3. ポート自動設定（重要）

   # ポート衝突を自動回避
   python -m agentflow.tools.port_manager my_app apps/my_app
   
   # 結果: .env ファイルが自動生成される
   # DB_MAIN_PORT=5432 (or 次の空きポート)
   # DB_HISTORY_PORT=5434
   # REDIS_PORT=6379
   # API_PORT=8000 (or 8001, 8002...)
   # FRONTEND_PORT=3000

4. ディレクトリ構造確認

   apps/my_app/
   ├── .env                    # ポート・認証情報（Git 除外）
   ├── .env.example            # 設定テンプレート
   ├── docker-compose.yml      # コンテナ構成
   ├── Dockerfile              # API コンテナ
   ├── alembic.ini             # DB マイグレーション
   ├── api.py                  # FastAPI エントリ
   ├── config/                 # 設定
   │   ├── __init__.py
   │   └── settings.yaml
   ├── db/init/                # 初期 SQL
   ├── migrations/             # Alembic
   ├── repositories/           # データアクセス層
   ├── routers/                # API ルーター
   ├── schemas/                # Pydantic スキーマ
   ├── services/               # ビジネスロジック
   └── tests/                  # テスト

フェーズ 2: 式様読取・設計（Design）

1. 要件分析

   • ユーザーストーリー抽出
   • エンティティ特定
   • API エンドポイント設計

2. DB スキーマ設計

   • repositories/models.py にモデル追加
   • db/init/01_schema.sql を更新

3. API 設計

   • routers/ に機能別ルーター追加
   • schemas/ にリクエスト/レスポンススキーマ追加

フェーズ 3: 実装・テスト（Implementation）

1. DB マイグレーション

   cd apps/my_app
   docker-compose up -d postgres-main redis
   alembic revision --autogenerate -m "add_entities"
   alembic upgrade head

2. サービス層実装

   • services/ にビジネスロジック追加

3. テスト作成・実行

   pytest tests/ -v

4. ループ: テスト失敗 → 修正 → 再テスト

ベストプラクティス

DB マイグレーション (Alembic)

# 新規マイグレーション作成
alembic revision --autogenerate -m "説明"

# マイグレーション適用
alembic upgrade head

# ロールバック
alembic downgrade -1

# 履歴確認
alembic history

Docker 操作

# コンテナ起動
docker-compose up -d

# DB のみ起動
docker-compose up -d postgres-main redis

# ログ確認
docker-compose logs -f api

# 停止・削除
docker-compose down -v

設定管理（環境統一）

.env ファイル構成:
├── APP_ENV          # development / staging / production
├── HOST             # localhost / IP / ドメイン
├── DB_MAIN_PORT     # PostgreSQL メイン
├── DB_HISTORY_PORT  # PostgreSQL 履歴
├── REDIS_PORT       # Redis
├── API_PORT         # FastAPI
├── FRONTEND_PORT    # React/Next.js
└── VITE_API_URL     # フロントエンドから API への URL

• 機密情報は .env で管理（Git 除外）
• アプリ設定は config/settings.yaml
• 環境変数でオーバーライド可能
• ポート衝突時: python -m agentflow.tools.port_manager で自動解決

ホスト設定（開発/本番統一）

環境	HOST 設定	備考
開発（ローカル）	localhost	127.0.0.1 も可
Docker 内から	host.docker.internal	ホスト側サービスへ
本番	実際の IP/ドメイン	外部公開

チェックリスト

• .env ファイルが作成されている（ポート設定済み）
• docker-compose.yml が正しく設定されている
• alembic.ini の DB URL が正しい
• models.py にエンティティが定義されている
• 初回マイグレーションが作成されている
• ヘルスチェックエンドポイントが動作する
• テストが実行可能
• 他の App とポートが衝突していない