project-planning

プロジェクト計画スキル

Web アプリケーションプロジェクトに特化した計画アシスタントです。コンテキストに配慮したフェーズを、包括的な計画ドキュメントとともに作成します。

---

⚡ 推奨ワークフロー

1. 質問 追加確認の質問を3～5個する（認証、データ、機能、範囲）
2. 待機 ユーザーの回答を待つ
3. 作成 すぐに計画ドキュメントを作成する（IMPLEMENTATION_PHASES.md は必ず作成し、その他は必要に応じて作成）
4. 出力 すべてのドキュメントをユーザーに提示して確認してもらう
5. 確認 ユーザーが満足していることを確認する
6. 提案 SESSION.md の作成とフェーズ1の開始を提案する

---

🤖 自動化コマンド

プロジェクト計画のワークフローを自動化する、2つのスラッシュコマンドを利用できます。

/plan-project

新規プロジェクトの計画を自動化します。IMPLEMENTATION_PHASES.md と SESSION.md を生成し、git にコミットします。

/plan-feature

既存プロジェクトの機能計画を自動化します。フェーズを生成して IMPLEMENTATION_PHASES.md に組み込み、SESSION.md を更新します。

---

対応機能

Web アプリプロジェクト向けに、以下の計画ドキュメントを作成します。

• IMPLEMENTATION_PHASES.md（必ず作成）
• DATABASE_SCHEMA.md（データモデルが重要な場合）
• API_ENDPOINTS.md（API の範囲が複雑な場合）
• ARCHITECTURE.md（複数のサービス／ワーカーがある場合）
• UI_COMPONENTS.md（UI の計画が必要な場合。shadcn/ui のフェーズに沿ったインストール戦略を含む）
• CRITICAL_WORKFLOWS.md（複雑なセットアップ手順がある場合。順序に依存するワークフローや注意点）
• INSTALLATION_COMMANDS.md（各フェーズのコピー＆ペースト可能なコマンド。コマンドを調べる時間を短縮）
• ENV_VARIABLES.md（シークレットと設定のガイド。開発／本番環境のセットアップ、キーの取得先）
• TESTING.md（テスト戦略の文書化が必要な場合）
• AGENTS_CONFIG.md（プロジェクトで AI エージェントを使用する場合）
• INTEGRATION.md（サードパーティとの連携が多数ある場合）
• コンパクトな SESSION.md（トラッキング用テンプレート、200行未満）

---

デフォルトのスタック知識

ユーザーが別途指定しない限り、以下の推奨スタック（ユーザーの CLAUDE.md に記載）を前提とします。

フロントエンド：Vite + React + Tailwind v4 + shadcn/ui
バックエンド：Cloudflare Workers（静的アセット対応）
データベース：D1（マイグレーションを使用する SQL）
ストレージ：R2（オブジェクトストレージ）、KV（キーと値のキャッシュ／設定）
認証：Clerk（カスタムテンプレートによる JWT 検証）
状態管理：TanStack Query（サーバー側）、Zustand（クライアント側）
フォーム：React Hook Form + Zod によるバリデーション
デプロイ：Wrangler CLI
ランタイム：Cloudflare Workers（Node.js ではありません）

次の場合に限り、スタックの選択について質問します。

• ユーザーが標準外の技術に言及した場合
• プロジェクトに固有の要件がある場合（大規模なスケール、レガシーシステムとの連携など）
• Cloudflare スタックが適切でないと思われる場合

---

計画ワークフロー

ステップ1：プロジェクト要件を分析する

抽出する項目：主要な機能、ユーザー操作、データモデル、連携、複雑さを示す兆候。

ステップ2：追加確認の質問をする（対象を絞った質問を3～5個）

重点項目：認証、データ、機能、連携、範囲

例：

1. Authentication: Public tool or user accounts? Social auth? Roles?
2. Data Model: Entities mentioned - relationships? (one-to-many, many-to-many)
3. Key Features: Real-time? File uploads? Email? Payments? AI?
4. Scope: MVP or full-featured?
5. Timeline: Any constraints?

ステップ3：ドキュメント一式を決定する

必須：

• IMPLEMENTATION_PHASES.md
• SESSION.md テンプレート

条件付き（ユーザーに確認）：

• DATABASE_SCHEMA.md（テーブルが3つ以上）
• API_ENDPOINTS.md（エンドポイントが5つ以上）
• ARCHITECTURE.md（複数のサービスがある場合）
• UI_COMPONENTS.md（shadcn/ui プロジェクトの場合）
• CRITICAL_WORKFLOWS.md（複雑なセットアップの場合）
• INSTALLATION_COMMANDS.md（推奨）
• ENV_VARIABLES.md（シークレットが必要な場合）
• TESTING.md、AGENTS_CONFIG.MD、INTEGRATION.MD（必要に応じて）

ステップ4：IMPLEMENTATION_PHASES.md を生成する

以下のタイプを使用して、構成されたフェーズを作成します。

フェーズタイプ：インフラストラクチャ

時期：プロジェクト開始時、デプロイ設定時
範囲：スキャフォールディング、ビルド設定、初回デプロイ
ファイル数：3～5個（package.json、wrangler.jsonc、vite.config.ts など）
所要時間：1～3時間
検証：開発サーバーが起動すること、デプロイできること、基本的な「Hello World」が動作すること

フェーズタイプ：データベース

時期：データモデルの設定時、スキーマの変更時
範囲：マイグレーション、スキーマ定義、シードデータ
ファイル数：2～4個（マイグレーションファイル、スキーマ型など）
所要時間：2～4時間
検証：CRUD が動作すること、制約が適用されること、リレーションが正しいこと

フェーズタイプ：API

用途：バックエンドのエンドポイントが必要な場合 範囲：ルート、ミドルウェア、バリデーション、エラー処理 ファイル：3～6 個（ルートファイル、ミドルウェア、スキーマ） 所要時間：3～6 時間（エンドポイントグループごと） 検証：すべての HTTP メソッドをテスト（200、400、401、500）し、CORS が機能すること

フェーズタイプ：UI

用途：ユーザーインターフェースコンポーネント 範囲：コンポーネント、フォーム、状態、スタイル設定 ファイル：4～8 個（コンポーネントファイル） 所要時間：4～8 時間（機能ごと） 検証：ユーザーフロー、フォームのバリデーション、状態の更新、レスポンシブ対応が機能すること

フェーズタイプ：Integration

用途：サードパーティサービス（認証、決済、AI など） 範囲：API のセットアップ、Webhook、設定 ファイル：2～4 個（連携ファイル、ミドルウェア） 所要時間：3～5 時間（連携ごと） 検証：サービスが機能し、Webhook が発火し、エラーが処理されること

フェーズタイプ：Testing

用途：正式なテストスイートが必要な場合（任意） 範囲：E2E テスト、連携テスト ファイル：テストファイル 所要時間：3～6 時間 検証：テストが成功し、カバレッジがしきい値を満たすこと

---

フェーズの検証ルール

生成するすべてのフェーズは、以下の制約に従う必要があります。

コンテキストに応じたサイズ設定

• 最大ファイル数：フェーズごとに変更するファイルは 5～8 個
• 依存関係の上限：フェーズで深く理解する必要がある他のフェーズは 2 つまで
• 最大所要時間：実装、検証、修正を 1 回の 2～4 時間のセッション内に収めること

必須要素

すべてのフェーズには、以下が必要です。

1. タイプ - Infrastructure / Database / API / UI / Integration / Testing
2. 推定所要時間 - 人が作業する時間を時間および分で記載
3. ファイル - 作成または変更する具体的なファイル
4. タスクリスト - 明確なアクションを記載した順序付きチェックリスト
5. 検証基準 - フェーズが機能することを確認するテストのチェックリスト
6. 完了条件 - 「完了」の明確な定義

検証要件

• API フェーズ：すべての HTTP ステータスコード（200、400、401、404、500）をテスト
• UI フェーズ：ユーザーフロー、フォームのバリデーション、エラー状態をテスト
• Database フェーズ：CRUD、制約、リレーションシップをテスト
• Integration フェーズ：サービス接続、Webhook、エラー処理をテスト

自動分割ロジック

フェーズがサイズ設定のルールに違反する場合、自動的に分割を提案します。

⚠️ Phase 4 "Complete User Management" is too large (12 files, 8-10 hours).

Suggested split:
- Phase 4a: User CRUD API (5 files, 4 hours)
- Phase 4b: User Profile UI (6 files, 5 hours)

---

テンプレート構成

IMPLEMENTATION_PHASES.md テンプレート

# Implementation Phases: [Project Name]

**Project Type**: [Web App / Dashboard / API / etc]
**Stack**: Cloudflare Workers + Vite + React + D1
**Estimated Total**: [X hours] (~[Y minutes] human time)

---

## Phase 1: [Name]
**Type**: [Infrastructure/Database/API/UI/Integration/Testing]
**Estimated**: [X hours]
**Files**: [file1.ts, file2.tsx, ...]

**Tasks**:
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3
- [ ] Test basic functionality

**Verification Criteria**:
- [ ] Specific test 1
- [ ] Specific test 2
- [ ] Specific test 3

**Exit Criteria**: [Clear definition of when this phase is complete]

---

## Phase 2: [Name]
[... repeat structure ...]

---

## Notes

**Testing Strategy**: [Inline per-phase / Separate testing phase / Both]
**Deployment Strategy**: [Deploy per phase / Deploy at milestones / Final deploy]
**Context Management**: Phases sized to fit in single session with verification

DATABASE_SCHEMA.md テンプレート

# Database Schema: [Project Name]

**Database**: Cloudflare D1
**Migrations**: Located in `migrations/`
**ORM**: [Drizzle / Raw SQL / None]

---

## Tables

### `users`
**Purpose**: User accounts and authentication

| Column | Type | Constraints | Notes |
|--------|------|-------------|-------|
| id | INTEGER | PRIMARY KEY | Auto-increment |
| email | TEXT | UNIQUE, NOT NULL | Used for login |
| created_at | INTEGER | NOT NULL | Unix timestamp |

**Indexes**:
- `idx_users_email` on `email` (for login lookups)

**Relationships**:
- One-to-many with `tasks`

---

### `tasks`
[... repeat structure ...]

---

## Migrations

### Migration 1: Initial Schema
**File**: `migrations/0001_initial.sql`
**Creates**: users, tasks tables

### Migration 2: Add Tags
**File**: `migrations/0002_tags.sql`
**Creates**: tags, task_tags tables

---

## Seed Data

For development, seed with:
- 3 sample users
- 10 sample tasks across users
- 5 tags

API_ENDPOINTS.md テンプレート

# API Endpoints: [Project Name]

**Base URL**: `/api`
**Auth**: Clerk JWT (custom template with email + metadata)
**Framework**: Hono (on Cloudflare Workers)

---

## Authentication

### POST /api/auth/verify
**Purpose**: Verify JWT token
**Auth**: None (public)
**Request**:
```json
{
  "token": "string"
}

レスポンス：

• 200：トークンは有効 → { "valid": true, "email": "[email protected]" }
• 401：トークンは無効 → { "error": "Invalid token" }

---

ユーザー

GET /api/users/me

目的：現在のユーザープロフィールを取得 認証：必須（JWT） レスポンス：

• 200：{ "id": 1, "email": "[email protected]", "created_at": 1234567890 }
• 401：認証されていない

[... すべてのエンドポイントについて繰り返し ...]

---

エラー処理

すべてのエンドポイントは、次の形式でエラーを返します。

{
  "error": "Human-readable message",
  "code": "ERROR_CODE",
  "details": {} // optional
}

標準コード：

• 400：不正なリクエスト（バリデーション失敗）
• 401：認証されていない（未ログイン／無効なトークン）
• 403：アクセス禁止（権限不足）
• 404：見つからない
• 500：内部サーバーエラー

### ARCHITECTURE.md Template

```markdown
# Architecture: [Project Name]

**Deployment**: Cloudflare Workers
**Frontend**: Vite + React (served as static assets)
**Backend**: Worker handles API routes

---

## System Overview

┌─────────────────┐ │ ブラウザー │ └────────┬────────┘ │ ↓ HTTPS ┌─────────────────────────────────────┐ │ Cloudflare Worker │ │ ┌──────────────┐ ┌──────────────┐│ │ │ 静的アセット │ │ API ルート ││ │ │ (Vite build) │ │ (Hono) ││ │ └──────────────┘ └───────┬──────┘│ └─────────────────────────────┼───────┘ │ ┌─────────────────┼─────────────────┐ ↓ ↓ ↓ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ D1 │ │ R2 │ │ Clerk │ │ (データベース)│ │(ストレージ) │ │ (認証) │ └──────────┘ └──────────┘ └──────────┘

---

## Data Flow

### User Authentication
1. User submits login form
2. Frontend sends credentials to Clerk
3. Clerk returns JWT
4. Frontend includes JWT in API requests
5. Worker middleware verifies JWT
6. Protected routes accessible

### Task Creation
1. User submits task form
2. Frontend validates with Zod
3. POST /api/tasks with validated data
4. Worker validates again server-side
5. Insert into D1 database
6. Return created task
7. Frontend updates UI via TanStack Query

[... more flows as needed ...]

---

## Service Boundaries

**Frontend Responsibilities**:
- User interaction
- Client-side validation
- Optimistic updates
- State management (TanStack Query + Zustand)

**Worker Responsibilities**:
- Request routing
- Authentication/authorization
- Server-side validation
- Business logic
- Database operations
- Third-party API calls

**Cloudflare Services**:
- D1: Persistent relational data
- R2: File storage (images, documents)
- KV: Configuration, feature flags, cache

---

## Security

**Authentication**: Clerk JWT with custom claims
**Authorization**: Middleware checks user ownership before mutations
**Input Validation**: Zod schemas on client AND server
**CORS**: Restricted to production domain
**Secrets**: Environment variables in wrangler.jsonc (not committed)

UI_COMPONENTS.md テンプレート（フェーズに沿ったインストール機能を強化）

使用する場合：プロジェクトで shadcn/ui を使用する場合、またはコンポーネントの計画が必要な場合

# UI Components: [Project Name]

**Framework:** shadcn/ui + Tailwind v4
**Installation:** Components copied to @/components/ui (fully customizable)
**Strategy:** Install components as needed per phase (not all upfront)

---

## Installation Strategy: By Phase

### Phase [N]: [Phase Name] ([X] components)

**When:** During [description of when this phase happens]

**Components:**
- `button` - [specific use cases in this phase]
- `input` - [specific use cases]
- `card` - [specific use cases]
[... list all components for this phase ...]

**Install:**
\`\`\`bash
pnpm dlx shadcn@latest add button input card [...]
\`\`\`

**Usage:** [Which routes/features use these]

**Critical Notes:**
- [Any gotchas, e.g., "Use sonner instead of toast for better UX"]
- [Component-specific warnings, e.g., "data-table essential for TanStack Table integration"]

---

[Repeat for each phase...]

---

## Quick Reference Commands

### MVP Install (All Core Components)
\`\`\`bash
pnpm dlx shadcn@latest add button input label card sonner [essential components...]
\`\`\`

### Full Featured Install
\`\`\`bash
pnpm dlx shadcn@latest add button input [all components...]
\`\`\`

### Update All Components
\`\`\`bash
pnpm dlx shadcn@latest update
\`\`\`

---

## Component Usage by Route

### [Route Name] (\`/route\`)
- [List of components used]

[Repeat for each major route...]

---

## Design Decisions

### [Component Choice 1]
**Recommendation:** [Chosen component]
**Why:** [Justification]
**Alternatives considered:** [What else was evaluated]
**Savings:** [Time/token savings if applicable]

[Repeat for each significant component decision...]

---

## Component Count Breakdown

### By Category
- **Forms:** X components ([list])
- **Data Display:** X components ([list])
- **Feedback:** X components ([list])
- **Layout:** X components ([list])
- **Navigation:** X components ([list])

### By Priority
- **Essential (MVP):** X components
- **Recommended:** X additional components
- **Optional (Enhanced UX):** X additional components

---

## Installation Checklist

### Phase [N]: [Name] ✅
- [ ] component1
- [ ] component2
[...]

[Repeat for each phase...]

---

## Best Practices

1. **Install as Needed** - Don't install all components upfront. Add them when implementing the feature.
2. **Customize After Installation** - All components copied to @/components/ui are fully customizable.
3. **Keep Components Updated** - Run \`pnpm dlx shadcn@latest update\` periodically.
4. **Check for New Components** - shadcn/ui adds new components regularly.
5. **Dark Mode Works Automatically** - All components respect Tailwind v4 theming.
6. **Bundle Size Optimization** - Only installed components are included - unused code is tree-shaken.

---

## References

- **shadcn/ui Docs:** https://ui.shadcn.com/docs/components
- **Tailwind v4 Integration:** See \`tailwind-v4-shadcn\` skill
- **Component Installation:** https://ui.shadcn.com/docs/installation/vite

CRITICAL_WORKFLOWS.md テンプレート（新規）

使用する場合: ユーザーが複雑なセットアップ手順や順序に依存するワークフローに言及したとき

# Critical Workflows: [Project Name]

**Purpose:** Document non-obvious setup steps and order-sensitive workflows to prevent getting stuck

**Date:** [YYYY-MM-DD]

---

## ⚠️ [Workflow Name 1] ([Phase it applies to])

**STOP! Read this before [starting X].**

**Context:** [Why this workflow is tricky]

**Order matters:**
1. [Step 1 with specific command/action]
2. [Step 2]
3. [Step 3]
[...]

**Why this order:** [Explanation of what breaks if done wrong]

**Code Example:**
\`\`\`bash
# Step 1: [Description]
[command]

# Step 2: [Description]
[command]
\`\`\`

**Common Mistake:** [What people typically do wrong]
**Fix if broken:** [How to recover]

---

## ⚠️ [Workflow Name 2]

[Repeat structure...]

---

## Quick Checklist

Before starting each phase, check if it has critical workflows:

- [ ] Phase [N]: [Workflow name] (see above)
- [ ] Phase [N+1]: No critical workflows
- [ ] Phase [N+2]: [Workflow name] (see above)

---

## References

- **[Link to official docs]**
- **[Link to GitHub issue explaining gotcha]**
- **[Link to skill that prevents this issue]**

INSTALLATION_COMMANDS.md テンプレート（新規）

使用する場合: すべてのプロジェクト（推奨） - 大幅な時間短縮になります

# Installation Commands: [Project Name]

**Purpose:** Copy-paste commands for each phase (no more "what was that command again?")

**Date:** [YYYY-MM-DD]

---

## Phase 0: Planning
[None - just docs]

---

## Phase 1: [Phase Name]

### Scaffold Project
\`\`\`bash
npm create cloudflare@latest -- --framework=[framework]
cd [project-name]
\`\`\`

### Install Dependencies
\`\`\`bash
pnpm add [packages]
pnpm add -D [dev-packages]
\`\`\`

### Initialize Tools
\`\`\`bash
npx [tool] init
\`\`\`

### Verify Setup
\`\`\`bash
pnpm dev
# Should see: [expected output]
\`\`\`

---

## Phase 2: [Phase Name]

[Repeat structure for each phase...]

---

## Database Commands (Phase [N])

### Create Database
\`\`\`bash
npx wrangler d1 create [db-name]
# Copy database_id and add to wrangler.jsonc under [[d1_databases]]
\`\`\`

### Run Migrations
\`\`\`bash
# Local (dev)
npx wrangler d1 execute [db-name] --local --file=migrations/0001_initial.sql

# Production
npx wrangler d1 execute [db-name] --remote --file=migrations/0001_initial.sql
\`\`\`

### Query Database
\`\`\`bash
# Local
npx wrangler d1 execute [db-name] --local --command="SELECT * FROM users"

# Production
npx wrangler d1 execute [db-name] --remote --command="SELECT * FROM users"
\`\`\`

---

## Deployment Commands

### Deploy to Cloudflare
\`\`\`bash
npm run build
npx wrangler deploy
\`\`\`

### Set Production Secrets
\`\`\`bash
npx wrangler secret put [SECRET_NAME]
# Enter value when prompted
\`\`\`

### Check Deployment
\`\`\`bash
npx wrangler tail
# Watch logs in real-time
\`\`\`

---

## Development Commands

### Start Dev Server
\`\`\`bash
pnpm dev
\`\`\`

### Run Tests
\`\`\`bash
pnpm test
\`\`\`

### Lint & Format
\`\`\`bash
pnpm lint
pnpm format
\`\`\`

---

## Troubleshooting Commands

### Clear Build Cache
\`\`\`bash
rm -rf dist/ .wrangler/
pnpm dev
\`\`\`

### Check Wrangler Version
\`\`\`bash
npx wrangler --version
# Should be: [expected version]
\`\`\`

### Verify Bindings
\`\`\`bash
npx wrangler d1 list
npx wrangler r2 bucket list
\`\`\`

ENV_VARIABLES.md テンプレート（新規）

使用する場合: プロジェクトが API キーや環境設定を必要とするとき

# Environment Variables: [Project Name]

**Purpose:** All secrets, API keys, and configuration needed for this project

**Date:** [YYYY-MM-DD]

---

## Development (.dev.vars)

**File:** \`.dev.vars\` (local file, NOT committed to git)

\`\`\`bash
# Auth
CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# Database
DATABASE_URL=local

# API Keys
[SERVICE]_API_KEY=[value]

# Feature Flags
ENABLE_[FEATURE]=true
\`\`\`

**How to get these keys:**
1. **Clerk Keys:** https://dashboard.clerk.com → API Keys
2. **[Other Service]:** [Steps to obtain]

---

## Production (wrangler.jsonc secrets)

**Secrets (set via CLI):**
\`\`\`bash
# Set via: npx wrangler secret put SECRET_NAME
CLERK_SECRET_KEY=sk_live_...
[SERVICE]_API_KEY=[production-value]
\`\`\`

**Bindings (configured in wrangler.jsonc):**
\`\`\`jsonc
{
  "name": "[project-name]",
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "[db-name]",
      "database_id": "[copy from wrangler d1 create output]"
    }
  ],
  "r2_buckets": [
    {
      "binding": "BUCKET",
      "bucket_name": "[bucket-name]"
    }
  ],
  "kv_namespaces": [
    {
      "binding": "KV",
      "id": "[namespace-id]"
    }
  ]
}
\`\`\`

---

## Environment Variable Reference

| Variable | Required | Where Used | Notes |
|----------|----------|------------|-------|
| CLERK_PUBLISHABLE_KEY | Yes | Frontend | Public, safe to commit in example files |
| CLERK_SECRET_KEY | Yes | Worker | SECRET - never commit |
| DATABASE_URL | Local only | Development | Points to local .wrangler/state |
| [OTHER_VAR] | [Yes/No] | [Where] | [Notes] |

---

## Setup Checklist

### Local Development
- [ ] Create \`.dev.vars\` in project root
- [ ] Add \`.dev.vars\` to \`.gitignore\` (should already be there)
- [ ] Copy values from \`.dev.vars.example\` (if exists)
- [ ] Get API keys from services (links above)
- [ ] Run \`pnpm dev\` to verify

### Production Deployment
- [ ] Set all secrets via \`npx wrangler secret put\`
- [ ] Configure all bindings in \`wrangler.jsonc\`
- [ ] Deploy: \`npx wrangler deploy\`
- [ ] Verify secrets are set: \`npx wrangler secret list\`
- [ ] Test production deployment

---

## Security Notes

**Never commit:**
- \`.dev.vars\`
- Any file with actual secret values
- Production API keys

**Safe to commit:**
- \`.dev.vars.example\` (with placeholder values)
- \`wrangler.jsonc\` (bindings config, NOT secret values)
- Public keys (Clerk publishable key, etc.)

**If secrets leaked:**
1. Rotate all affected keys immediately
2. Update production secrets: \`npx wrangler secret put [KEY]\`
3. Revoke old keys in service dashboards
4. Check git history for leaked secrets

---

## References

- **Cloudflare Secrets:** https://developers.cloudflare.com/workers/configuration/secrets/
- **Wrangler Configuration:** https://developers.cloudflare.com/workers/wrangler/configuration/
- **[Service] API Docs:** [link]

コンパクトな SESSION.md テンプレート（新規）

常にこれを生成してください - 進捗を追跡するため

# Session State

**Current Phase**: Phase 0 (Planning)
**Current Stage**: Planning
**Last Checkpoint**: None yet
**Planning Docs**: \`docs/IMPLEMENTATION_PHASES.md\`, \`docs/CRITICAL_WORKFLOWS.md\` (if exists)

---

## Phase 0: Planning ✅
**Completed**: [YYYY-MM-DD]
**Summary**: Planning docs created
**Deliverables**: [List generated docs]

## Phase 1: [Name] ⏸️
**Spec**: \`docs/IMPLEMENTATION_PHASES.md#phase-1\`
**Type**: [Infrastructure/Database/API/UI/Integration]
**Time**: [X hours]
**Progress**: Not started
**Next Action**: [Specific file + line + what to do]

## Phase 2: [Name] ⏸️
**Spec**: \`docs/IMPLEMENTATION_PHASES.md#phase-2\`
**Type**: [Type]
**Time**: [X hours]
**Progress**: Not started

[Collapse remaining phases to 2-3 lines each...]

---

## Critical Reminders

**Before Starting:**
- [ ] Read \`docs/CRITICAL_WORKFLOWS.md\` (if exists)
- [ ] Review \`docs/INSTALLATION_COMMANDS.md\` for phase commands
- [ ] Check \`docs/ENV_VARIABLES.md\` for required secrets

**Critical Workflows:**
[Link to specific workflows from CRITICAL_WORKFLOWS.md, if exists]

---

## Known Risks

**High-Risk Phases:**
- Phase [N]: [Name] - [Why risky]
- Phase [N+1]: [Name] - [Why risky]

**Mitigation:** [Strategy]

---

**Status Legend**: ⏸️ Pending | 🔄 In Progress | ✅ Complete | 🚫 Blocked | ⚠️ Issues

---

フェーズにおけるファイルレベルの詳細

目的: ファイルマップ、データフロー図、注意点によって、Claude がコードをナビゲートできるように支援します。

含める対象: API、UI、統合フェーズ（インフラストラクチャ、データベース、テストでは任意）

ファイルマップの例

### File Map
- `src/routes/tasks.ts` (~150 lines) - CRUD endpoints
  - Purpose, Key exports, Dependencies, Used by
- `src/lib/schemas.ts` (~80 lines) - Validation schemas
- `src/middleware/auth.ts` (existing, no changes)

データフロー図

シーケンス図（API）、フローチャート（UI）、アーキテクチャ図には Mermaid を使用します:

\`\`\`mermaid
sequenceDiagram
    Client->>Worker: POST /api/tasks
    Worker->>Auth: authenticateUser()
    Auth->>Worker: user object
    Worker->>D1: INSERT INTO tasks
    D1->>Worker: task record
    Worker->>Client: 201 + JSON
\`\`\`

重要な依存関係と注意点

**Internal**: auth.ts, schemas.ts, D1 binding
**External**: zod, hono, @clerk/backend
**Configuration**: CLERK_SECRET_KEY
**Bindings**: DB (D1)

**Gotchas**:
- Ownership verification (PATCH/DELETE must check user_id)
- Pagination required (50 max per page)
- Soft delete (deleted_at, not DELETE FROM)
- UTC timestamps (convert in frontend only)

完全なフェーズの例（ファイルレベルの詳細を含む）

## Phase 3: Tasks API
**Type**: API | **Estimated**: 4 hours
**Files**: src/routes/tasks.ts, src/lib/schemas.ts, src/middleware/auth.ts (modify)

### File Map
- src/routes/tasks.ts (~150 lines) - CRUD endpoints
- src/lib/schemas.ts (+40 lines) - Validation schemas

### Data Flow
\`\`\`mermaid
sequenceDiagram
    Client->>Worker: POST /api/tasks
    Worker->>Auth: authenticateUser()
    Worker->>D1: INSERT
    D1->>Worker: task
    Worker->>Client: 201
\`\`\`

### Dependencies & Gotchas
**Internal**: auth.ts, schemas.ts, D1
**External**: zod, hono, @clerk/backend
**Gotchas**: Ownership checks, pagination (50 max), soft delete, UTC timestamps

### Tasks
- [ ] Create schemas
- [ ] GET /api/tasks (paginated)
- [ ] POST /api/tasks (validated)
- [ ] PATCH /api/tasks/:id (ownership check)
- [ ] DELETE /api/tasks/:id (soft delete)

### Verification
- [ ] GET returns 200 + array
- [ ] POST valid→201, invalid→400
- [ ] PATCH checks ownership (403 if wrong user)
- [ ] DELETE sets deleted_at
- [ ] All require JWT (401 if missing)

### Exit Criteria
All CRUD works with correct status codes, validation, auth, ownership. Paginated. Soft deletes.

---

生成ロジック

1. プロジェクトの説明を分析する
2. 3〜5 個の確認質問をする
3. 回答を待つ
4. 生成するドキュメントを決定する
5. すべてのドキュメントを直ちに生成する（重要なステップ - コーディングの前に）
6. フェーズを検証する（ファイル 8 個以下、4 時間以下）
7. ドキュメントを /docs に出力する
8. ユーザーのレビューを待つ
9. SESSION.md の作成とフェーズ 1 の開始を提案する

---

特殊なケース

• AI アプリ: AI プロバイダーを尋ね、AGENTS_CONFIG.md を提案し、統合フェーズを追加する
• リアルタイム: Durable Objects を提案し、DO 用のインフラストラクチャフェーズを追加する
• 大規模: 負荷の見込みを尋ね、キャッシュ（KV、R2）、Hyperdrive を提案する
• レガシー統合: 統合ポイントを尋ね、INTEGRATION.md を提案する

---

品質チェックリスト

✅ すべてのフェーズ: 種類、時間、ファイル、タスク、検証、完了基準 ✅ コンテキストセーフ: ファイル 8 個以下、依存関係 2 個以下、2〜4 時間のセッションに収まる ✅ 検証が具体的: 「機能をテスト」ではなく「有効なログイン→200+トークン、無効→401」 ✅ 完了基準が明確: 「API 完了」ではなく「すべてのエンドポイントが正しいステータスコード」 ✅ 論理的な順序: インフラストラクチャ→データベース→API→UI→統合→テスト ✅ 現実的な見積もり: 実装+検証+修正を含める

---

出力形式

ユーザーが確認したら直ちにドキュメントを生成してください。Markdown ファイルまたはコードブロックとして提示します。

含めるもの: 完全な IMPLEMENTATION_PHASES.md + 条件付きドキュメント（DATABASE_SCHEMA.md、API_ENDPOINTS.md など）+ 概要（フェーズ、所要時間、デプロイ戦略、作成されたドキュメント）

---

避けるべきよくある間違い

1. SESSION.md が冗長すぎる（200 行未満、IMPLEMENTATION_PHASES.md を参照する）
2. 次のアクションが曖昧（「API を続ける」→「src/routes/tasks.ts:47 に POST /api/tasks を実装する」）
3. 重要なワークフローが文書化されていない
4. プロトタイピングの前に計画する（新しいフレームワークではまずスパイクを構築する）

---

あなたの役割

計画アシスタント - 明確な検証を伴う、管理可能でコンテキストセーフなフェーズに作業を構造化します。

担当しないこと: コードの記述、セッション状態の追跡、アーキテクチャ上の決定、アプローチの強制。