docs(dev): ローカル開発セットアップガイド(docs/dev/local-setup.md)

[win2cot]

Phase 1 Setup 1-6: ローカル開発セットアップガイド(docs/dev/local-setup.md)

概要

Setup 1-1〜1-5 の成果(Docker Compose + Keycloak Realm + Flyway + application.yml + web/ skeleton)をまとめ、新規開発者(将来の自分含む)が docs/dev/local-setup.md に従えば 30 分以内に local 環境を立ち上げられる ガイドを作成する。

詳細仕様: docs/architecture/infrastructure-plan.md v5 §5.2(Setup 1-6)。

背景

ローカル環境の構築手順が頭の中だけにあると、再現性が低い + Sprint 0 着手後の開発者(claude-impl bot 含む)が困る。明示的にドキュメント化することで:

• 新規環境セットアップが script ライクに進む
• Setup 1-7(E2E 動作確認)の手順と一貫性
• 将来の onboarding コスト削減

実装内容

A. docs/dev/local-setup.md の構成(目次案)

1. 前提条件
   • WSL 2(Ubuntu 24.04)
   • Docker Desktop + WSL integration 有効化
   • JDK 21(SDKMAN! 推奨)
   • gh CLI(Issue 操作用)
2. リポジトリ取得
   • git clone git@github.com:win2cot/tasks-webapi.git
3. Docker Compose 起動
   • docker compose -f docker-compose.local.yml up -d
   • 起動確認(docker compose ps)
4. 環境変数設定
   • .env.local のテンプレートと使い方
   • env vars 一覧
5. ./gradlew :webapi:bootRun 起動
   • source .env.local && ./gradlew :webapi:bootRun
   • Flyway migration が走ることの確認
6. Keycloak Realm 動作確認
   • admin console http://localhost:8080(admin / admin)
   • Test User でログイン → JWT 取得
7. Frontend skeleton 起動
   • web/ を軽量 HTTP サーバで配信
   • ブラウザで http://localhost:5500/index.html を開く
8. 動作確認 E2E(Setup 1-7 とリンク)
   • ログイン → JWT 取得 → tasks-webapi API call → 成功の流れ
9. トラブルシューティング
   • Docker WSL integration が動かない場合
   • MySQL ポート競合
   • Keycloak Realm import 失敗
   • Flyway 接続エラー

B. 既存設計書との整合

• .claude/CLAUDE.md の Commands セクションとリンク
• docs/specs/開発計画書.md v1.3 §4.3.1 / §11.1 と整合

C. スクリーンショット(任意、後追い可)

• Keycloak admin console / Realm Settings 等のスクショ(将来補強)

受入条件

• docs/dev/local-setup.md が存在
• 上記目次の全セクション(1〜9)が記載されている
• 各手順がコマンドレベルでコピペ可能
• env vars 一覧が表形式で記載されている
• トラブルシューティング(9)に最低 3 項目以上の Q&A
• 30 分以内に新規環境を立ち上げられる粒度であること(目視確認 / セルフチェック)
• Setup 1-1〜1-5 の成果物への参照(リンク)が網羅されている

想定影響範囲

• Sprint 0 着手前の開発者 onboarding
• Setup 1-7 E2E テスト手順との一貫性
• claude-impl bot が将来このガイドを参照可能性あり

関連

• 親 tracker Issue: [Phase 1 Infra] Setup 0-2 + Sprint 0-5 Infra ストリーム横断 tracker #206
• Milestone: Phase 1 Setup 1(due 2026-06-13)
• 依存: Setup 1-1〜1-5 完了後(成果物を踏まえてドキュメント化)
• 隣接: Setup 1-7(E2E 動作確認、手順を共有)
• 詳細仕様: docs/architecture/infrastructure-plan.md v5 §5.2

備考

• task-type: task-type:design(docs 主体)
• 優先度: priority/p2(完了が望ましいが Sprint 0 着手後の補強も可)
• area: area/docs

[claude-automation-impl]

実装着手宣言

方針サマリ

docs/dev/local-setup.md を新規作成します。

対応内容:

1. Setup 1-1〜1-5 の成果物(docker-compose.local.yml / keycloak/realm-export/ / Flyway / application.yml / web/)を精査し、実際のコマンドと設定値を反映
2. Issue 本文の目次案(セクション 1〜9)を網羅
3. env vars 一覧を表形式で記載(DATASOURCE_URL / DATASOURCE_USERNAME / DATASOURCE_PASSWORD / OIDC_ISSUER_URI)
4. テストユーザー情報(admin@example.com / tenant1-admin@example.com / tenant1-member1@example.com)と初期パスワードを記載
5. Keycloak は port 18080(docker-compose.local.yml の実際の設定)で記載
6. トラブルシューティング 4 項目以上を Q&A 形式で記載

スコープ外: スクリーンショットは「将来補強可」として省略