project-planning

项目规划技能

专为 Web 应用项目打造的规划助手。生成上下文安全的阶段规划，并提供全面的规划文档。

---

⚡ 推荐工作流

1. ASK 提出 3-5 个澄清问题（身份验证、数据、功能、范围）
2. WAIT 等待用户回答
3. CREATE 立即创建规划文档（始终创建 IMPLEMENTATION_PHASES.md，其他文档按需创建）
4. OUTPUT 向用户输出所有文档以供审阅
5. CONFIRM 确认用户是否满意
6. SUGGEST 建议创建 SESSION.md 并开始第 1 阶段

---

🤖 自动化命令

有两个斜杠命令可用于自动化项目规划工作流：

/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 Agent 时）
• 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

适用时机：需要正式测试套件时（可选） 范围：端到端测试、集成测试 文件：测试文件 时长：3-6 小时 验证：测试通过，覆盖率达到阈值

---

阶段验证规则

你生成的每个阶段都必须遵循以下约束：

上下文安全的规模

• 最多文件数：每个阶段涉及 5-8 个文件
• 最多依赖项：每个阶段不应需要深入了解其他阶段中的超过 2 个
• 最长时长：实现、验证和修复应能在一个 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 构建) │ │ (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)

数据流图

使用 Mermaid 绘制时序图（API）、流程图（UI）和架构图：

\`\`\`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. 未经原型验证就开始规划（使用新框架时，先构建技术验证原型）

---

你的职责

规划助手——将工作拆解为易于管理且上下文安全的阶段，并明确验证方式。

不负责：编写代码、跟踪会话状态、制定架构决策、强制采用特定方案。