@einja/dev-cli 0.1.38 → 0.1.40

package/presets/default/docs/einja/example/specs/issues/issue999-example-task/qa-tests/story1.md

@@ -0,0 +1,101 @@
+# Story 1: マジックリンク認証 QAテスト結果
+
+## テスト対象
+- **ストーリー**: Story 1 - マジックリンク認証
+- **対象AC**: AC1.1〜AC1.9
+- **実装日**: YYYY-MM-DD
+- **テスター**: task-qa
+- **最終更新**: YYYY-MM-DD HH:MM
+
+## テストサマリー
+| ステータス | 件数 |
+|----------|-----|
+| ✅ PASS | 0 |
+| ❌ FAIL | 0 |
+| ⚠️ PARTIAL | 0 |
+
+---
+
+## 必須自動テスト結果
+
+### 実行コマンド
+```bash
+pnpm test
+pnpm test:e2e
+pnpm lint
+pnpm build
+pnpm typecheck
+```
+
+### 結果
+| テスト項目 | ステータス | 備考 |
+|----------|----------|------|
+| ユニットテスト | - | - |
+| E2Eテスト | - | - |
+| Lintチェック | - | - |
+| ビルドチェック | - | - |
+| 型チェック | - | - |
+
+---
+
+## AC1.1: 有効なメールアドレスでMagic Linkをリクエストできる
+
+### 受け入れ条件
+- Given: ログイン画面にアクセスした
+- When: 有効なメールアドレスを入力して送信
+- Then: 成功メッセージが表示され、メールが送信される
+- 検証レベル: Integration
+
+### テストシナリオ
+
+| No | 手順 | 確認項目 | 期待値 | 結果 | 備考 |
+|----|------|---------|--------|------|------|
+| 1 | POST /api/auth/magic-link (email: test@example.com) | ステータスコード | 200 | - | 正常系 |
+| 2 | - | レスポンスボディ | {"success":true} | - | - |
+| 3 | - | メール送信イベント | イベント発火確認 | - | - |
+
+### ステータス: - （未実施）
+
+#### エビデンス
+- ログファイル: `qa-tests/evidence/story1/AC1-1-*.log`
+
+---
+
+## AC1.2: 無効なメールアドレスでエラーが返る
+
+### 受け入れ条件
+- Given: ログイン画面にアクセスした
+- When: 無効なメールアドレス形式で送信
+- Then: バリデーションエラーが表示される
+- 検証レベル: Integration
+
+### テストシナリオ
+
+| No | 手順 | 確認項目 | 期待値 | 結果 | 備考 |
+|----|------|---------|--------|------|------|
+| 1 | POST /api/auth/magic-link (email: "invalid") | ステータスコード | 400 | - | バリデーションエラー |
+| 2 | - | エラーメッセージ | 「有効なメールアドレスを入力してください」 | - | - |
+
+### ステータス: - （未実施）
+
+#### エビデンス
+- ログファイル: `qa-tests/evidence/story1/AC1-2-*.log`
+
+---
+
+## Story 1 全体結果サマリー
+
+### 全体結果
+- **全体ステータス**: - （未実施）
+- **完了AC**: 0/9
+- **テスト合格率**: 0% (0/0)
+
+---
+
+## 報告と対応
+
+### 失敗原因分類
+- [ ] **A: 実装ミス** → task-executerへ差し戻し
+- [ ] **B: 要件齟齬** → requirements.md修正
+- [ ] **C: 設計不備** → design.md修正
+- [ ] **D: 環境問題** → qa再実行

package/presets/default/docs/einja/example/specs/issues/issue999-example-task/qa-tests/story2.md

@@ -0,0 +1,70 @@
+# Story 2: プロフィール管理 QAテスト結果
+
+## テスト対象
+- **ストーリー**: Story 2 - プロフィール管理
+- **対象AC**: AC2.1〜AC2.3
+- **実装日**: YYYY-MM-DD
+- **テスター**: task-qa
+- **最終更新**: YYYY-MM-DD HH:MM
+
+## テストサマリー
+| ステータス | 件数 |
+|----------|-----|
+| ✅ PASS | 0 |
+| ❌ FAIL | 0 |
+| ⚠️ PARTIAL | 0 |
+
+---
+
+## 必須自動テスト結果
+
+### 結果
+| テスト項目 | ステータス | 備考 |
+|----------|----------|------|
+| ユニットテスト | - | - |
+| E2Eテスト | - | - |
+| Lintチェック | - | - |
+| ビルドチェック | - | - |
+| 型チェック | - | - |
+
+---
+
+## AC2.1: ログイン済みユーザーがプロフィールを取得できる
+
+### 受け入れ条件
+- Given: ユーザーがログイン済み
+- When: GET /api/users/me を呼び出す
+- Then: プロフィール情報がJSON形式で返る
+- 検証レベル: Integration
+
+### テストシナリオ
+
+| No | 手順 | 確認項目 | 期待値 | 結果 | 備考 |
+|----|------|---------|--------|------|------|
+| 1 | 認証トークンを取得 | - | - | - | 前提 |
+| 2 | GET /api/users/me (Authorization: Bearer {token}) | ステータスコード | 200 | - | - |
+| 3 | - | レスポンスにemail, nameが含まれる | JSON形式のプロフィール | - | - |
+
+### ステータス: - （未実施）
+
+#### エビデンス
+- ログファイル: `qa-tests/evidence/story2/AC2-1-*.log`
+
+---
+
+## Story 2 全体結果サマリー
+
+### 全体結果
+- **全体ステータス**: - （未実施）
+- **完了AC**: 0/3
+- **テスト合格率**: 0% (0/0)
+
+---
+
+## 報告と対応
+
+### 失敗原因分類
+- [ ] **A: 実装ミス** → task-executerへ差し戻し
+- [ ] **B: 要件齟齬** → requirements.md修正
+- [ ] **C: 設計不備** → design.md修正
+- [ ] **D: 環境問題** → qa再実行

package/presets/default/docs/einja/example/specs/issues/issue999-example-task/qa-tests/story3.md

@@ -0,0 +1,69 @@
+# Story 3: セキュリティ通知 QAテスト結果
+
+## テスト対象
+- **ストーリー**: Story 3 - セキュリティ通知
+- **対象AC**: AC3.1〜AC3.6
+- **実装日**: YYYY-MM-DD
+- **テスター**: task-qa
+- **最終更新**: YYYY-MM-DD HH:MM
+
+## テストサマリー
+| ステータス | 件数 |
+|----------|-----|
+| ✅ PASS | 0 |
+| ❌ FAIL | 0 |
+| ⚠️ PARTIAL | 0 |
+
+---
+
+## 必須自動テスト結果
+
+### 結果
+| テスト項目 | ステータス | 備考 |
+|----------|----------|------|
+| ユニットテスト | - | - |
+| E2Eテスト | - | - |
+| Lintチェック | - | - |
+| ビルドチェック | - | - |
+| 型チェック | - | - |
+
+---
+
+## AC3.1: 新しいデバイスからログイン時にセキュリティ通知メールが送信される
+
+### 受け入れ条件
+- Given: ユーザーが既にログイン履歴がある
+- When: 新しいデバイスからログイン
+- Then: セキュリティ通知メールが送信される
+- 検証レベル: Integration
+
+### テストシナリオ
+
+| No | 手順 | 確認項目 | 期待値 | 結果 | 備考 |
+|----|------|---------|--------|------|------|
+| 1 | 新しいUser-Agentでログインリクエスト | ログイン成功 | 200 OK | - | - |
+| 2 | - | セキュリティ通知メール | メール送信イベント発火 | - | - |
+
+### ステータス: - （未実施）
+
+#### エビデンス
+- ログファイル: `qa-tests/evidence/story3/AC3-1-*.log`
+
+---
+
+## Story 3 全体結果サマリー
+
+### 全体結果
+- **全体ステータス**: - （未実施）
+- **完了AC**: 0/6
+- **テスト合格率**: 0% (0/0)
+
+---
+
+## 報告と対応
+
+### 失敗原因分類
+- [ ] **A: 実装ミス** → task-executerへ差し戻し
+- [ ] **B: 要件齟齬** → requirements.md修正
+- [ ] **C: 設計不備** → design.md修正
+- [ ] **D: 環境問題** → qa再実行

package/{scaffolds → presets/default/docs/einja}/instructions/deployment-setup.md

@@ -23,6 +23,88 @@
 
 ---
 
+## 0. ゼロからの統合初期構築フロー
+
+新しいプロジェクトまたは新しい開発者が環境を構築する際の統合フローです。
+
+### 前提条件
+
+以下のツール・アカウントが必要です:
+
+| ツール | インストール方法 | 用途 |
+|--------|----------------|------|
+| Volta | `curl https://get.volta.sh \| bash` | Node.jsバージョン管理 |
+| pnpm | `volta install pnpm` | パッケージ管理 |
+| Docker | [Docker Desktop](https://www.docker.com/products/docker-desktop/) | PostgreSQL実行 |
+| GitHub CLI (`gh`) | `brew install gh` | GitHub操作 |
+| Vercel CLI | `pnpm add -g vercel` | Vercelデプロイ |
+| Neon CLI (`neonctl`) | `npm install -g neonctl` | Neonデータベース管理 |
+| dotenvx | `brew install dotenvx/brew/dotenvx` | 環境変数暗号化 |
+
+### 構築ステップ
+
+#### Step 1: リポジトリのクローンと依存関係インストール
+
+```bash
+git clone <repository-url>
+cd <project-name>
+pnpm install
+```
+
+#### Step 2: Neon初期設定
+
+1. [Neon Console](https://console.neon.tech/) でAPI Keyを取得
+2. `.env.personal` に `NEON_API_KEY=<取得したキー>` を設定
+3. プロジェクト作成・ブランチ設定
+
+詳細は [Neon CLI リファレンス](./neon-cli-reference.md) のセクション5「実践例」を参照。
+
+#### Step 3: Vercel初期設定
+
+1. [Vercel Dashboard](https://vercel.com/account/tokens) でトークンを取得
+2. `.env.personal` に `VERCEL_TOKEN=<取得したトークン>` を設定
+3. `vercel link --project=<プロジェクト名> --yes` でプロジェクト接続
+
+詳細は [Vercel CLI リファレンス](./vercel-cli-reference.md) を参照。
+
+#### Step 4: GitHub Secrets一括設定
+
+`.env.keys` から秘密鍵を自動抽出してGitHub Secretsに設定:
+
+```bash
+for key_name in PREVIEW PRODUCTION DEVELOP STAGING; do
+  value=$(grep "DOTENV_PRIVATE_KEY_${key_name}" .env.keys | cut -d'=' -f2 | tr -d '"'"'"')
+  [ -n "$value" ] && gh secret set "DOTENV_PRIVATE_KEY_${key_name}" --body "$value"
+done
+```
+
+詳細はセクション6「GitHub Secrets登録」を参照。
+
+#### Step 5: ローカル環境変数設定
+
+```bash
+pnpm env:update
+```
+
+ウィザードに従って個人トークンと環境変数を設定。
+詳細は [環境変数セットアップ](./environment-setup.md) を参照。
+
+#### Step 6: 初回起動
+
+```bash
+pnpm dev:setup    # 初回セットアップ（DB起動・マイグレーション含む）
+pnpm dev:bg       # 開発サーバー起動
+```
+
+#### Step 7: 動作確認
+
+- [ ] ローカル開発サーバーにアクセスできる
+- [ ] ログインが正常に動作する
+- [ ] PRを作成してCI（GitHub Actions）が正常に動作する
+- [ ] Preview環境にデプロイされる
+
+---
+
 ## 1. 必要なSecrets一覧
 
 ### 必須Secrets
@@ -104,17 +186,19 @@ pnpm env:update
 
 Preview環境用のDBブランチは以下のルールで自動作成されます：
 
-| PRブランチ名 | 作成されるDBブランチ名 | 親ブランチ |
-|------------|---------------------|----------|
-| `feature/user-auth` | `preview/feature-user-auth` | `main` |
-| `fix/login-bug` | `preview/fix-login-bug` | `main` |
-| `feat/dashboard` | `preview/feat-dashboard` | `main` |
+| 環境 | PR番号 | DBブランチ名 | 説明 |
+|------|-------|------------|------|
+| production | - | production | 本番環境 |
+| develop | - | development | 開発環境 |
+| preview | #123 | preview/pr-123 | PR番号から自動生成 |
 
 **重要**:
 - DBブランチ名はGitブランチ名から自動変換（`/`→`-`、小文字化）
 - プレフィックス `preview/` が自動付与
 - PR作成時に自動作成、PRクローズ時に自動削除
 
+> **Neon CLI/APIの詳細**: [Neon CLI リファレンス](./neon-cli-reference.md) を参照してください。
+
 ### Vercel Postgres
 
 ```bash
@@ -306,10 +390,10 @@ gh secret set RAILWAY_SERVICE_ID --body "サービスID"
 # 2. 「New repository secret」で以下を追加
 
 # --- 復号鍵（.env.keysから取得） ---
-gh secret set DOTENV_PRIVATE_KEY_PREVIEW --body "$(grep DOTENV_PRIVATE_KEY_PREVIEW .env.keys | cut -d'\"' -f2)"
-gh secret set DOTENV_PRIVATE_KEY_PRODUCTION --body "$(grep DOTENV_PRIVATE_KEY_PRODUCTION .env.keys | cut -d'\"' -f2)"
-gh secret set DOTENV_PRIVATE_KEY_DEVELOP --body "$(grep DOTENV_PRIVATE_KEY_DEVELOP .env.keys | cut -d'\"' -f2)"
-gh secret set DOTENV_PRIVATE_KEY_STAGING --body "$(grep DOTENV_PRIVATE_KEY_STAGING .env.keys | cut -d'\"' -f2)"
+gh secret set DOTENV_PRIVATE_KEY_PREVIEW --body "$(grep DOTENV_PRIVATE_KEY_PREVIEW .env.keys | cut -d= -f2 | tr -d '"'"'"')"
+gh secret set DOTENV_PRIVATE_KEY_PRODUCTION --body "$(grep DOTENV_PRIVATE_KEY_PRODUCTION .env.keys | cut -d= -f2 | tr -d '"'"'"')"
+gh secret set DOTENV_PRIVATE_KEY_DEVELOP --body "$(grep DOTENV_PRIVATE_KEY_DEVELOP .env.keys | cut -d= -f2 | tr -d '"'"'"')"
+gh secret set DOTENV_PRIVATE_KEY_STAGING --body "$(grep DOTENV_PRIVATE_KEY_STAGING .env.keys | cut -d= -f2 | tr -d '"'"'"')"
 
 # --- Vercel ---
 gh secret set VERCEL_TOKEN --body "取得したトークン"

package/{scaffolds → presets/default/docs/einja}/instructions/environment-setup.md

@@ -155,7 +155,6 @@ dotenvx decrypt -f .env.production
 ├── .env.local              # ローカル開発用（暗号化・Git追跡）★
 ├── .env.develop            # dev検証サーバー用（暗号化・Git追跡）
 ├── .env.production         # 本番環境用（暗号化・Git追跡）
-├── .env.ci                 # CI/CD用（暗号化・Git追跡）
 ├── .env.keys               # 秘密鍵（Git除外・1Password等で共有）
 ├── .env                    # .env.localを復号したもの（Git除外）
 └── .env.personal           # 個人用トークン（Git除外）
@@ -316,13 +315,13 @@ git push
 
 ```bash
 # CI用秘密鍵を登録
-gh secret set DOTENV_PRIVATE_KEY_CI --body "$(grep DOTENV_PRIVATE_KEY_CI .env.keys | cut -d= -f2)"
+gh secret set DOTENV_PRIVATE_KEY_CI --body "$(grep DOTENV_PRIVATE_KEY_CI .env.keys | cut -d= -f2 | tr -d '"'"'"')"
 
 # Preview用秘密鍵を登録（Preview環境を使う場合）
-gh secret set DOTENV_PRIVATE_KEY_PREVIEW --body "$(grep DOTENV_PRIVATE_KEY_PREVIEW .env.keys | cut -d= -f2)"
+gh secret set DOTENV_PRIVATE_KEY_PREVIEW --body "$(grep DOTENV_PRIVATE_KEY_PREVIEW .env.keys | cut -d= -f2 | tr -d '"'"'"')"
 
 # 本番用秘密鍵を登録（必要に応じて）
-gh secret set DOTENV_PRIVATE_KEY_PRODUCTION --body "$(grep DOTENV_PRIVATE_KEY_PRODUCTION .env.keys | cut -d= -f2)"
+gh secret set DOTENV_PRIVATE_KEY_PRODUCTION --body "$(grep DOTENV_PRIVATE_KEY_PRODUCTION .env.keys | cut -d= -f2 | tr -d '"'"'"')"
 ```
 
 ### Vercel環境変数への登録
@@ -489,6 +488,155 @@ dotenvx run -f .env -f .env.local -- <command>
 - [dotenvx公式ドキュメント](https://dotenvx.com/docs)
 - [dotenvx暗号化の仕組み](https://dotenvx.com/encryption)
 - [direnv公式ドキュメント](https://direnv.net/)
+
+## チーム共有設定変更フロー
+
+チーム全体で共有する環境変数（`.env.develop`, `.env.preview`, `.env.production` 等）を変更する手順:
+
+### 手順
+
+1. **復号化**: 暗号化されたファイルを復号
+   ```bash
+   dotenvx decrypt -f .env.develop --stdout > .env.develop.tmp
+   ```
+
+2. **編集**: 一時ファイルを編集
+   ```bash
+   # エディタで .env.develop.tmp を編集
+   ```
+
+3. **元ファイルに反映**: 編集内容を元ファイルにコピー
+   ```bash
+   cp .env.develop.tmp .env.develop
+   rm .env.develop.tmp
+   ```
+
+4. **再暗号化**: 変更を暗号化
+   ```bash
+   dotenvx encrypt -f .env.develop
+   ```
+
+5. **コミット**: 暗号化されたファイルをコミット
+   ```bash
+   git add .env.develop
+   git commit -m "chore: develop環境の環境変数を更新"
+   ```
+
+> **⚠️ 警告**: `.env.production` を編集する場合は、本番環境への影響を十分に確認してから行ってください。
+
+## 新規環境変数追加フロー
+
+プロジェクトに新しい環境変数を追加する手順:
+
+### 手順
+
+1. **`.env.example` にキーを追加**（デフォルト値またはプレースホルダー）
+   ```bash
+   # .env.example に追記
+   NEW_API_KEY=your-api-key-here
+   ```
+
+2. **各環境ファイルに追加**
+   - `.env.local` - ローカル開発用の値
+   - `.env.develop` - 開発環境用の値
+   - `.env.preview` - プレビュー環境用の値
+   - `.env.production` - 本番環境用の値
+   - `.env.staging` - ステージング環境用の値（該当する場合）
+
+3. **暗号化ファイルの編集**
+   暗号化されたファイル（`.env.local`, `.env.develop`, `.env.production`, `.env.preview`）を編集する場合：
+   ```bash
+   # 復号してテンポラリファイルに出力
+   dotenvx decrypt -f .env.local --stdout > .env.local.tmp
+
+   # エディタで編集
+   vi .env.local.tmp  # または好みのエディタ
+
+   # 元ファイルを削除して編集済みファイルをリネーム
+   rm .env.local
+   mv .env.local.tmp .env.local
+
+   # 再暗号化
+   dotenvx encrypt -f .env.local
+   ```
+
+   **注意**: 同じ手順を他の環境ファイルにも適用してください。
+
+4. **非暗号化ファイルの編集**
+   非暗号化ファイル（`.env`, `.env.personal`）は直接編集可能：
+   ```bash
+   # .env.personal を直接編集（GITHUB_TOKEN等の個人トークン）
+   vi .env.personal
+
+   # .env は通常 .env.local から自動生成されるため、直接編集は非推奨
+   # .env.local を編集して pnpm dev:setup を再実行する
+   ```
+
+5. **環境固有の変数かどうかを確認**
+   新規変数が以下に該当する場合、他環境への展開要否を確認：
+   - **全環境共通**: すべての環境ファイルに同じ値を追加
+   - **環境固有**: 該当環境のみに追加（例: `PRODUCTION_ONLY_FLAG=true`）
+   - **開発専用**: `.env.local`, `.env.develop`, `.env.preview` のみに追加
+
+6. **暗号化ファイルの再暗号化**
+   編集が完了したら、すべての環境ファイルを再暗号化：
+   ```bash
+   dotenvx encrypt -f .env.local
+   dotenvx encrypt -f .env.develop
+   dotenvx encrypt -f .env.preview
+   dotenvx encrypt -f .env.production
+   ```
+
+7. **デプロイ環境への同期**
+   新規環境変数をCI/CDやホスティングサービスに反映させる必要がある場合：
+
+   - **GitHub Secrets（CI/CD用）**:
+     秘密鍵が変更された場合は [デプロイメントセットアップ](./deployment-setup.md) のセクション6を参照
+     ```bash
+     # 新規Secretの追加
+     gh secret set NEW_API_KEY --body "your-api-key-value"
+     ```
+
+   - **Vercel環境変数（本番/プレビュー用）**:
+     初回は手動同期、以降はGitHub Actionsが自動同期
+     ```bash
+     # Vercel CLIで設定
+     vercel env add NEW_API_KEY production
+     vercel env add NEW_API_KEY preview
+     ```
+
+   - **詳細手順**: [deployment-setup.md](./deployment-setup.md) を参照
+
+8. **コミット**
+   暗号化ファイルと `.env.example` の変更をコミット：
+   ```bash
+   git add .env.example .env.local .env.develop .env.preview .env.production
+   git commit -m "chore: NEW_API_KEY 環境変数を追加"
+   git push
+   ```
+
+## .env.personal のセキュリティ
+
+`.env.personal` は個人のAPIトークン・キーを管理するファイルです。
+
+### 管理対象トークン
+
+| トークン | 取得先 | 用途 |
+|---------|-------|------|
+| `VERCEL_TOKEN` | [Vercel Dashboard](https://vercel.com/account/tokens) | Vercel CLI認証 |
+| `NEON_API_KEY` | [Neon Console](https://console.neon.tech/account/api-keys) | Neon CLI認証 |
+| `GITHUB_TOKEN` | [GitHub Settings](https://github.com/settings/tokens) | GitHub API認証 |
+
+### セキュリティルール
+
+- **Git管理対象外**: `.gitignore` で除外済み
+- **dotenvx暗号化対象外**: 個人ファイルのため暗号化不要
+- **権限設定**: ファイル作成後は必ず実行
+  ```bash
+  chmod 600 .env.personal
+  ```
+- **ローテーション推奨**: 90日ごとにトークンを更新することを推奨
+- **共有禁止**: 他の開発者とトークンを共有しないこと
 <!-- @einja:managed:end -->
 
 ---

package/{scaffolds → presets/default/docs/einja}/instructions/local-server-environment-and-worktree.md

@@ -424,6 +424,20 @@ docker compose ps
 4. **ポート番号を確認**:
    `worktree.config.json`の`postgres.port`が正しいか確認してください。
 
+### `pnpm dev:setup` 失敗時の診断
+
+`pnpm dev:setup` コマンドが失敗した場合、以下のテーブルでエラーパターンを診断し、対処してください。
+
+| エラーパターン | 診断 | 対処 |
+|---------------|------|------|
+| `ENOENT: no such file or directory, open '.env.keys'` | `.env.keys`不在 | メインworktreeからコピー、または1Password等から取得して手動配置 |
+| `Error: connect ECONNREFUSED 127.0.0.1:25432` | PostgreSQL未起動 | `docker compose up -d postgres` → 10秒待機 → `docker compose exec postgres pg_isready` |
+| `prisma:error Error in schema` | Prismaスキーマエラー | エラーメッセージを確認し、`packages/server-core/prisma/schema.prisma`を修正 |
+| `Node.js version mismatch` / `Unsupported engine` | Node.jsバージョン不一致 | `volta install node@22` または `fnm use 22` |
+| `pnpm: command not found` | pnpm未インストール | `volta install pnpm@10` または `npm i -g pnpm@10` |
+| `EACCES: permission denied` | ファイル権限エラー | 対象ファイルの権限確認（`ls -la`）、必要に応じて`chmod`で修正 |
+| `Cannot find module` | 依存関係不足 | `pnpm install` を再実行、`node_modules`を削除して再インストール |
+
 ### Prismaマイグレーションが失敗する
 
 **症状**: `Error: P1001: Can't reach database server`
@@ -527,6 +541,91 @@ pnpm build
 2. プロジェクトのREADME.md
 3. GitHub Issuesで既存の問題を検索
 4. チームメンバーに相談
+
+## Prisma単独セットアップ
+
+開発サーバー全体を起動せずにPrismaのみを操作する場合のコマンド:
+
+| コマンド | 説明 | 用途 |
+|---------|------|------|
+| `pnpm db:generate` | Prismaクライアント生成 | スキーマ変更後の型生成 |
+| `pnpm db:push` | スキーマをDBに反映 | プロトタイピング時（マイグレーション不使用） |
+| `pnpm db:migrate:deploy` | マイグレーション実行 | 本番環境・CI環境でのスキーマ適用 |
+| `pnpm db:migrate:dev` | マイグレーション作成・適用 | 開発時の新しいマイグレーション作成 |
+| `pnpm db:studio` | Prisma Studio起動 | ブラウザでのDB閲覧・編集 |
+
+### 使い分け
+
+- **開発中のスキーマ変更**: `db:push`（マイグレーションファイルを作成せずに即座に反映）
+- **マイグレーション確定時**: `db:migrate:dev`（マイグレーションファイルを生成）
+- **デプロイ時**: `db:migrate:deploy`（既存マイグレーションを適用）
+
+> **注意**: `db:push` はマイグレーション履歴を作成しません。チームで共有する変更は必ず `db:migrate:dev` でマイグレーションを作成してください。
+
+## 包括的ヘルスチェック
+
+開発環境の状態を一括で確認するためのチェック項目:
+
+### 1. ランタイム環境
+
+```bash
+# Node.jsバージョン（v22.16.0が期待値）
+node -v
+
+# pnpmバージョン
+pnpm -v
+
+# Volta確認
+volta list
+```
+
+### 2. Docker / PostgreSQL
+
+```bash
+# Dockerコンテナ状態
+docker-compose ps
+
+# PostgreSQL接続確認（ポート25432）
+docker-compose exec postgres pg_isready -U postgres -p 5432
+```
+
+### 3. 環境変数ファイル
+
+```bash
+# 必須ファイルの存在確認
+for f in .env .env.local .env.keys .env.personal; do
+  [ -f "$f" ] && echo "✅ $f" || echo "❌ $f が見つかりません"
+done
+
+# .env.personalの権限確認
+stat -f "%Lp" .env.personal 2>/dev/null | grep -q "600" && echo "✅ .env.personal: 権限OK (600)" || echo "⚠️ .env.personal: chmod 600 を実行してください"
+```
+
+### 4. Prismaスキーマ
+
+```bash
+# スキーマ検証
+pnpm db:generate
+
+# マイグレーション状態
+pnpm db:migrate:status 2>/dev/null || echo "マイグレーション状態の確認にはDB接続が必要です"
+```
+
+### 5. 開発サーバー
+
+```bash
+# サーバー状態確認
+pnpm dev:status
+```
+
+### 6. CLI ツール
+
+```bash
+# 各CLIの存在確認
+for cmd in gh vercel neonctl dotenvx; do
+  command -v $cmd >/dev/null 2>&1 && echo "✅ $cmd: $(command -v $cmd)" || echo "❌ $cmd: 未インストール"
+done
+```
 <!-- @einja:managed:end -->
 
 ---