@einja/dev-cli 0.1.6

package/scaffolds/steering/product.md

@@ -0,0 +1,540 @@
+# 製品ビジョン
+
+TODO
+以下はサンプルで、まだDBは未作成です。
+
+## 概要
+
+このドキュメントでは、Turborepo + Next.jsモノレポプロジェクトの製品ビジョン、ビジネス価値、主要なステークホルダー、成功指標を定義します。
+
+このプロジェクトは、エンタープライズグレードのモノレポアーキテクチャを構築し、複数のアプリケーション（Web、Admin、Cron Worker）と共有パッケージ（Server Core）を統合することで、高速なビルドパイプライン、型安全性、優れた開発者体験を実現します。
+
+---
+
+## 目次
+
+1. [製品の目的](#1-製品の目的)
+2. [主要なステークホルダー](#2-主要なステークホルダー)
+3. [ビジネス価値](#3-ビジネス価値)
+4. [主要機能](#4-主要機能)
+5. [成功指標](#5-成功指標)
+6. [技術的目標](#6-技術的目標)
+7. [開発原則](#7-開発原則)
+8. [ロードマップ](#8-ロードマップ)
+
+---
+
+## 1. 製品の目的
+
+### ビジョン
+
+**「開発チームが高速かつ安全に、スケーラブルなWebアプリケーションを構築できるモノレポ基盤を提供する」**
+
+### ミッション
+
+1. **開発速度の向上**: Turborepoのリモートキャッシュにより、ビルド時間を80%以上削減
+2. **型安全性の保証**: エンドツーエンドの型推論により、ランタイムエラーを設計時点で防止
+3. **保守性の向上**: 4層アーキテクチャとデザインパターンにより、コードの可読性と拡張性を確保
+4. **開発者体験の最適化**: 30分以内の環境セットアップ、統一されたツールチェーン、明確なドキュメント
+
+### 解決する課題
+
+| 課題 | 現状 | 解決策 |
+|------|------|--------|
+| **コードの重複** | 複数アプリで同じロジックを重複実装 | @repo/server-coreによる共通化 |
+| **ビルド時間の増大** | モノレポ全体のビルドに数分かかる | Turborepo Remote Cacheで80%削減 |
+| **型の不整合** | フロントエンドとバックエンドで型が一致しない | Hono Client + Zodによるエンドツーエンド型推論 |
+| **設定管理の複雑性** | 各アプリで個別に設定を管理 | ルート設定の継承による一元管理 |
+| **デプロイの複雑性** | 複数環境への手動デプロイ | GitHub Actionsによる自動デプロイ |
+| **開発環境構築の時間** | 新規参加者が環境構築に半日以上かかる | 30分以内の環境セットアップ |
+
+---
+
+## 2. 主要なステークホルダー
+
+### 2.1 バックエンド開発者
+
+**ニーズ**:
+- 型安全なAPI開発環境
+- データベーススキーマの一元管理
+- エラーハンドリングの統一パターン
+- ビジネスロジックの再利用性
+
+**提供価値**:
+- Hono + Result型パターンによる型安全なAPI開発
+- Prismaによる型安全なデータアクセス
+- 4層アーキテクチャによる責務の明確化
+- @repo/server-coreによるコード共有
+
+**ユーザーストーリー**:
+> **As a** バックエンド開発者
+> **I want to** Hono + Result型 + Mapperを用いた4層アーキテクチャを構築したい
+> **So that** 型安全で保守性の高いサーバーサイドアプリケーションを開発できる
+
+### 2.2 フロントエンド開発者
+
+**ニーズ**:
+- バックエンドAPIとの型整合性
+- 効率的なデータフェッチングとキャッシュ管理
+- 型安全なフォーム実装
+- 再利用可能なUIコンポーネント
+
+**提供価値**:
+- Hono Clientによるエンドツーエンド型推論
+- Tanstack Queryによる統一的なデータ管理
+- React Hook Form + zodResolverによる型安全なフォーム
+- 共通コンポーネントライブラリ
+
+**ユーザーストーリー**:
+> **As a** フロントエンド開発者
+> **I want to** Hono Client + Tanstack Queryを用いた型安全なAPIクライアントを構築したい
+> **So that** エンドツーエンドの型安全性を確保し、効率的なデータ取得・キャッシュ管理ができる
+
+### 2.3 システム運用者
+
+**ニーズ**:
+- 定期実行タスクの管理
+- バッチ処理の監視
+- ジョブの冪等性保証
+- エラー通知とログ管理
+
+**提供価値**:
+- Cron Workerによる定期実行タスク
+- JobCoordinatorによるジョブロック機構
+- Railway Cronによるスケジューリング
+- 統一的なエラーハンドリングとログ
+
+**ユーザーストーリー**:
+> **As a** システム運用者
+> **I want to** バックグラウンドジョブをCLIコマンドとして実行できるようにしたい
+> **So that** Railway Cronから定期実行タスクやバッチ処理を実行できる
+
+### 2.4 管理者
+
+**ニーズ**:
+- 直感的な管理画面UI
+- データの一括操作
+- ユーザー管理機能
+- システム設定の変更
+
+**提供価値**:
+- 管理者専用のAdminアプリケーション
+- 統一されたデザインシステム
+- セキュアな認証・認可
+- データ操作の監査ログ
+
+**ユーザーストーリー**:
+> **As a** 管理者
+> **I want to** 管理画面アプリケーション（admin）をセットアップしたい
+> **So that** システムの管理機能を開発できる
+
+### 2.5 新規参加の開発者
+
+**ニーズ**:
+- 明確なセットアップ手順
+- 統一されたコーディング規約
+- 豊富なドキュメント
+- すぐに開発を開始できる環境
+
+**提供価値**:
+- 30分以内の環境セットアップ
+- Steering/Feature docsによる包括的なドキュメント
+- Biomeによる統一されたコード規約
+- サンプル実装（Post CRUD）
+
+**ユーザーストーリー**:
+> **As a** 新規参加の開発者
+> **I want to** 開発環境のセットアップ手順が明確に記載されたドキュメントを参照したい
+> **So that** 迅速にプロジェクトに参加して開発を開始できる
+
+### 2.6 開発チーム全体
+
+**ニーズ**:
+- コード品質の自動保証
+- 並行開発での干渉回避
+- ビルド時間の短縮
+- 自動デプロイ
+
+**提供価値**:
+- GitHub ActionsによるCI/CD
+- Turborepoによる並列ビルド
+- Remote Cacheによる80%ビルド時間削減
+- ワークスペースの独立性
+
+**ユーザーストーリー**:
+> **As a** 開発チーム
+> **I want to** GitHub Actionsで自動テスト・ビルド・デプロイを実行したい
+> **So that** コード品質を保ち、自動的にデプロイできる
+
+---
+
+## 3. ビジネス価値
+
+### 3.1 開発速度の向上
+
+**削減時間**:
+- 環境セットアップ: **数時間 → 30分以内** （90%削減）
+- ビルド時間: **100秒 → 14秒** （86%削減、Remote Cache使用時）
+- 型エラー修正: **事前検出により実装時間50%削減**
+
+**ROI（投資対効果）**:
+- チーム5人、月間ビルド回数1,000回と仮定
+- ビルド時間削減: `(100s - 14s) × 1,000 = 86,000秒 = 約24時間/月`
+- **月間24時間の開発時間を創出**
+
+### 3.2 コード品質の向上
+
+**エラー検出**:
+- 型エラー: **設計時点で100%検出**（TypeScript strict mode）
+- リントエラー: **コミット前に自動検出**（Biome + pre-commit hooks）
+- テストエラー: **CI/CDで自動検出**（Vitest + Playwright）
+
+**保守性**:
+- コードの重複: **70%削減**（@repo/server-coreによる共通化）
+- 技術的負債: **4層アーキテクチャによる継続的なリファクタリング可能性**
+
+### 3.3 スケーラビリティ
+
+**チームのスケール**:
+- ワークスペースの独立性により、**複数チームの並行開発が可能**
+- 設定の継承により、**新しいアプリの追加が容易**
+
+**機能のスケール**:
+- モジュール化されたアーキテクチャにより、**機能追加が高速**
+- 共有パッケージにより、**新機能の全アプリへの展開が迅速**
+
+### 3.4 運用コストの削減
+
+**デプロイコスト**:
+- Vercel: **サーバーレスによる従量課金**（アイドル時コストゼロ）
+- Railway: **Cronジョブのみの実行**（常時稼働不要）
+
+**保守コスト**:
+- 自動テスト: **手動テスト工数を80%削減**
+- 統一されたツール: **学習コストの削減**
+
+---
+
+## 4. 主要機能
+
+### 4.1 アプリケーション
+
+| アプリケーション | 用途 | 技術スタック | デプロイ先 |
+|----------------|------|-------------|-----------|
+| **web** | ユーザー向けWebアプリ | Next.js 14 App Router | Vercel |
+| **admin** | 管理画面 | Next.js 14 App Router | Vercel |
+| **cron-worker** | バッチ処理・定期実行 | Node.js CLI (tsx) | Railway |
+
+### 4.2 共有パッケージ
+
+| パッケージ | 責務 | 主要コンポーネント |
+|-----------|------|-------------------|
+| **@repo/server-core** | サーバーサイド共通ロジック | Prisma Client、Repository、UseCase、Mapper |
+
+### 4.3 インフラストラクチャ
+
+| カテゴリ | 機能 | 技術 |
+|---------|------|------|
+| **モノレポ管理** | ビルドオーケストレーション | Turborepo |
+| **パッケージ管理** | 依存関係管理 | pnpm workspaces |
+| **CI/CD** | 自動テスト・ビルド・デプロイ | GitHub Actions |
+| **リモートキャッシュ** | ビルド成果物の共有 | Vercel Remote Cache |
+| **データベース** | データ永続化 | PostgreSQL (Prisma) |
+| **認証** | ユーザー認証 | Auth.js (NextAuth) |
+| **メール送信** | トランザクショナルメール | Resend |
+| **ストレージ** | ファイル保存 | S3/Cloudflare R2 |
+
+### 4.4 開発ツール
+
+| ツール | 用途 | 特徴 |
+|-------|------|------|
+| **TypeScript** | 型安全性 | strict mode、型アサーション禁止 |
+| **Biome** | Linter + Formatter | 高速、統一された規約 |
+| **Vitest** | ユニット・インテグレーションテスト | 高速、TypeScript完全対応 |
+| **Playwright** | E2Eテスト | クロスブラウザ対応 |
+| **Hono** | APIフレームワーク | 型安全、軽量 |
+| **Zod** | バリデーション | スキーマファースト |
+| **Tanstack Query** | データフェッチング | キャッシュ管理、楽観的更新 |
+| **React Hook Form** | フォーム管理 | 型安全、高パフォーマンス |
+
+### 4.5 コア機能（サンプル実装）
+
+**Post機能（CRUD）**:
+- 投稿一覧表示（ページネーション）
+- 投稿作成（フォームバリデーション）
+- 投稿詳細表示
+- 投稿編集・削除
+- 管理画面での投稿管理
+
+**目的**: モノレポ構成での実践的なCRUD機能の実装パターンを提供
+
+---
+
+## 5. 成功指標
+
+### 5.1 開発効率指標
+
+| 指標 | 目標値 | 測定方法 |
+|------|--------|----------|
+| **環境セットアップ時間** | 30分以内 | 新規参加者のフィードバック |
+| **ビルド時間（キャッシュあり）** | 80%以上削減 | CI/CD ログから測定 |
+| **ビルド時間（apps/web）** | 5秒以下 | `turbo run build --summarize` |
+| **型エラー検出率** | 100% | TypeScript strict mode有効化 |
+| **コード重複率** | 30%以下 | SonarQubeなどの静的解析ツール |
+
+### 5.2 コード品質指標
+
+| 指標 | 目標値 | 測定方法 |
+|------|--------|----------|
+| **テストカバレッジ（server-core）** | 80%以上 | Vitest coverage report |
+| **テストカバレッジ（apps）** | 70%以上 | Vitest coverage report |
+| **型アサーション使用率** | 0% | Biome lint ルール違反数 |
+| **Lint違反数** | 0件 | CI/CDでのBiomeチェック |
+| **CI/CD成功率** | 95%以上 | GitHub Actions実行結果 |
+
+### 5.3 運用効率指標
+
+| 指標 | 目標値 | 測定方法 |
+|------|--------|----------|
+| **デプロイ頻度** | 1日10回以上 | GitHub Actionsデプロイ履歴 |
+| **デプロイ所要時間** | 5分以内 | CI/CDログ |
+| **平均修復時間（MTTR）** | 1時間以内 | インシデント管理システム |
+| **Cronジョブ成功率** | 99%以上 | Railway Cron実行ログ |
+
+### 5.4 開発者体験指標
+
+| 指標 | 目標値 | 測定方法 |
+|------|--------|----------|
+| **開発者満足度** | 4.5/5以上 | 四半期ごとのアンケート |
+| **ドキュメント充実度** | 全機能カバー | ドキュメントレビュー |
+| **問い合わせ対応時間** | 24時間以内 | GitHub Issues対応履歴 |
+
+---
+
+## 6. 技術的目標
+
+### 6.1 型安全性
+
+**目標**: **エンドツーエンドの型推論により、ランタイムエラーをゼロに近づける**
+
+**実現方法**:
+1. TypeScript strict mode有効化
+2. 型アサーション（`as`）の禁止（Biome設定）
+3. Hono Clientによるフロントエンド⇔バックエンド型共有
+4. Zodスキーマによるランタイムバリデーション
+5. Prismaによるデータベース型安全性
+
+**測定**: 型エラー検出率100%、型アサーション使用率0%
+
+### 6.2 パフォーマンス
+
+**目標**: **ビルド時間を80%以上削減し、開発サイクルを高速化**
+
+**実現方法**:
+1. Turborepoのインクリメンタルビルド
+2. Vercel Remote Cacheによるチーム間キャッシュ共有
+3. 並列実行による効率化
+4. 依存関係の最適化
+
+**測定**: ビルド時間 100秒 → 14秒（86%削減）
+
+### 6.3 保守性
+
+**目標**: **4層アーキテクチャにより、コードの可読性と拡張性を確保**
+
+**実現方法**:
+1. Layered Architecture（Presentation → Application → Domain → Infrastructure）
+2. Repository Patternによる抽象化
+3. Mapper Patternによる変換層の分離
+4. Result型によるエラーハンドリングの統一
+5. index.ts完全不使用方針によるインポート元の明確化
+
+**測定**: コード重複率30%以下、技術的負債の継続的削減
+
+### 6.4 スケーラビリティ
+
+**目標**: **モノレポ構成により、複数チームの並行開発を可能にする**
+
+**実現方法**:
+1. ワークスペースの独立性
+2. 共有パッケージによるコード再利用
+3. タスクの並列実行
+4. 環境変数の階層的管理
+
+**測定**: チーム数に比例したスループット向上
+
+### 6.5 開発者体験
+
+**目標**: **30分以内の環境セットアップと、統一されたツールチェーン**
+
+**実現方法**:
+1. 明確なREADMEとセットアップガイド
+2. Biomeによる統一されたコード規約
+3. Worktreeサポート（動的ポート割り当て）
+4. 充実したドキュメント（Steering/Feature docs）
+
+**測定**: 開発者満足度4.5/5以上、セットアップ時間30分以内
+
+---
+
+## 7. 開発原則
+
+### 7.1 DRY原則（Don't Repeat Yourself）
+
+**原則**: **コードの重複を避け、@repo/server-coreで共通化**
+
+**実践例**:
+- データベースアクセス: Repositoryパターンで一元化
+- バリデーション: Zodスキーマで統一
+- エラーハンドリング: Result型で標準化
+
+### 7.2 型安全ファースト
+
+**原則**: **型アサーションを使わず、型推論に依存**
+
+**実践例**:
+- Hono Clientによる自動型推論
+- Zodスキーマからの型生成
+- Prismaによる型安全なクエリ
+
+### 7.3 設計と実装の分離
+
+**原則**: **設計書（docs/specs/）には実装コードを書かない**
+
+**実践例**:
+- 設計書: Class名、関数シグネチャ、アーキテクチャ図のみ
+- 実装: src/配下のコードで具体化
+
+### 7.4 テスト駆動開発（TDD）
+
+**原則**: **Given-When-Then形式でテストを記述**
+
+**実践例**:
+```typescript
+describe('UserRepository', () => {
+  it('有効なユーザーデータを渡すと、ユーザーが作成される', async () => {
+    // Given: 有効なデータ
+    const userData = { email: 'test@example.com', name: 'Test User' }
+
+    // When: createメソッドを呼び出す
+    const result = await userRepository.create(userData)
+
+    // Then: 成功結果が返る
+    expect(result.isSuccess).toBe(true)
+  })
+})
+```
+
+### 7.5 インクリメンタルな改善
+
+**原則**: **小さなPRで頻繁にマージし、継続的に改善**
+
+**実践例**:
+- 1PR = 1タスクグループ
+- 1日10回以上のデプロイ
+- 継続的なリファクタリング
+
+---
+
+## 8. ロードマップ
+
+### Phase 0: 基盤構築（P0 - 必須）
+
+**目標**: Turborepoモノレポの初期化と基本設定
+
+**タスク**:
+1. ✅ Turborepoモノレポの初期化
+2. ✅ ルート設定ファイルの構築（TypeScript、Biome）
+3. ✅ Next.jsアプリケーション（web）の構築
+4. ✅ Adminアプリケーション（admin）の構築
+5. ✅ Cron Workerアプリケーション（cron-worker）の構築
+6. ✅ Server Coreパッケージ（@repo/server-core）の構築
+
+**成果物**:
+- 動作するモノレポ環境
+- 各アプリケーションの開発サーバー起動
+- Prisma Clientの生成
+
+### Phase 1: ビルドパイプライン最適化（P0 - 必須）
+
+**目標**: Turborepoビルドパイプラインの最適化
+
+**タスク**:
+1. ✅ turbo.jsonのパイプライン定義
+2. ✅ 依存関係の設定
+3. ✅ キャッシュ戦略の設定
+4. ✅ 並列ビルドの有効化
+
+**成果物**:
+- 最適化されたビルドパイプライン
+- キャッシュによる高速ビルド
+
+### Phase 2: リモートキャッシュとCI/CD（P1 - 重要）
+
+**目標**: Vercel Remote CacheとGitHub Actionsの設定
+
+**タスク**:
+1. ✅ Vercel Remote Cacheの設定
+2. ✅ GitHub Actions CI/CDパイプライン構築
+3. ✅ 自動デプロイの設定
+
+**成果物**:
+- 80%以上のビルド時間削減
+- 自動テスト・ビルド・デプロイ
+
+### Phase 3: アーキテクチャ実装（P0 - 必須）
+
+**目標**: 4層アーキテクチャとコア機能の実装
+
+**タスク**:
+1. ✅ Result型パターンの実装
+2. ✅ Repository + Mapperパターンの実装
+3. ✅ Hono APIアプリケーションの構築
+4. ✅ Hono Client + Tanstack Queryの統合
+5. ✅ React Hook Formの統合
+
+**成果物**:
+- 型安全なバックエンドAPI
+- 型安全なフロントエンドクライアント
+
+### Phase 4: サンプル実装（P1 - 重要）
+
+**目標**: Post CRUD機能の実装
+
+**タスク**:
+1. ✅ Post APIエンドポイントの実装
+2. ✅ Web Post一覧・作成・詳細ページ
+3. ✅ Admin Post管理ページ
+4. ✅ Tanstack Queryによるキャッシュ管理
+
+**成果物**:
+- 実践的なCRUD機能のサンプル
+
+### Phase 5: ドキュメント整備（P1 - 重要）
+
+**目標**: 開発環境セットアップドキュメントの作成
+
+**タスク**:
+1. ✅ README.mdの作成
+2. ✅ Steering documentationの作成
+3. ✅ Feature documentationの作成
+4. ✅ Worktreeサポートスクリプトの作成
+
+**成果物**:
+- 包括的なドキュメント
+- 30分以内の環境セットアップ
+
+---
+
+## まとめ
+
+このプロジェクトは、**開発速度**、**型安全性**、**保守性**、**開発者体験**を最優先し、エンタープライズグレードのモノレポ基盤を構築します。
+
+**主要な成功指標**:
+- ✅ 環境セットアップ時間: **30分以内**
+- ✅ ビルド時間削減: **80%以上**
+- ✅ 型エラー検出率: **100%**
+- ✅ テストカバレッジ: **80%以上**（server-core）
+- ✅ 開発者満足度: **4.5/5以上**
+
+すべての開発活動は、このビジョンと原則に従って実施してください。