project-planning by jezweb/claude-skills
npx skills add https://github.com/jezweb/claude-skills --skill project-planning专为 Web 应用程序项目设计的规划助手。生成上下文安全的阶段,并提供全面的规划文档。
提供两个斜杠命令来自动化项目规划工作流程:
/plan-project为新项目自动化规划:生成 IMPLEMENTATION_PHASES.md + SESSION.md + git 提交。
/plan-feature为现有项目自动化功能规划:生成阶段,集成到 IMPLEMENTATION_PHASES.md 中,更新 SESSION.md。
你为 Web 应用程序项目生成规划文档:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
除非用户另有说明,否则假设使用以下首选技术栈(来自他们的 CLAUDE.md):
前端 : Vite + React + Tailwind v4 + shadcn/ui 后端 : Cloudflare Workers with Static Assets 数据库 : D1(带迁移的 SQL) 存储 : R2(对象存储),KV(键值缓存/配置) 认证 : Clerk(带自定义模板的 JWT 验证) 状态管理 : TanStack Query(服务器端),Zustand(客户端) 表单 : React Hook Form + Zod 验证 部署 : Wrangler CLI 运行时 : Cloudflare Workers(非 Node.js)
仅在以下情况下询问技术栈选择:
提取:核心功能、用户交互、数据模型、集成、复杂性信号。
关注:认证、数据、功能、集成、范围
示例 :
1. 认证:是公开工具还是需要用户账户?社交登录?角色?
2. 数据模型:提到的实体 - 关系?(一对多,多对多)
3. 关键功能:实时?文件上传?邮件?支付?AI?
4. 范围:最小可行产品还是完整功能?
5. 时间线:有任何限制吗?
始终生成 :
条件性生成(询问用户):
使用以下类型创建结构化阶段:
时机 : 项目开始,部署设置 范围 : 脚手架,构建配置,初始部署 文件 : 3-5 个(package.json, wrangler.jsonc, vite.config.ts 等) 持续时间 : 1-3 小时 验证 : 开发服务器运行,可以部署,基本的 "Hello World" 正常工作
时机 : 数据模型设置,模式变更 范围 : 迁移,模式定义,种子数据 文件 : 2-4 个(迁移文件,模式类型) 持续时间 : 2-4 小时 验证 : CRUD 工作,约束强制执行,关系正确
时机 : 需要后端端点 范围 : 路由,中间件,验证,错误处理 文件 : 3-6 个(路由文件,中间件,模式) 持续时间 : 3-6 小时(每组端点) 验证 : 所有 HTTP 方法测试通过(200, 400, 401, 500),CORS 工作
时机 : 用户界面组件 范围 : 组件,表单,状态,样式 文件 : 4-8 个(组件文件) 持续时间 : 4-8 小时(每个功能) 验证 : 用户流程工作,表单验证,状态更新,响应式
时机 : 第三方服务(认证、支付、AI 等) 范围 : API 设置,Webhooks,配置 文件 : 2-4 个(集成文件,中间件) 持续时间 : 3-5 小时(每个集成) 验证 : 服务工作,Webhooks 触发,错误处理
时机 : 需要正式测试套件(可选) 范围 : E2E 测试,集成测试 文件 : 测试文件 持续时间 : 3-6 小时 验证 : 测试通过,覆盖率满足阈值
你生成的每个阶段必须遵循以下约束:
每个阶段必须包含:
如果一个阶段违反了大小规则,自动建议拆分:
⚠️ 阶段 4 "完成用户管理" 太大(12 个文件,8-10 小时)。
建议拆分:
- 阶段 4a: 用户 CRUD API(5 个文件,4 小时)
- 阶段 4b: 用户资料 UI(6 个文件,5 小时)
# 实施阶段:[项目名称]
**项目类型**:[Web 应用 / 仪表板 / API / 等]
**技术栈**:Cloudflare Workers + Vite + React + D1
**预计总计**:[X 小时](约 [Y 分钟] 人工时间)
---
## 阶段 1:[名称]
**类型**:[基础设施/数据库/API/UI/集成/测试]
**预计**:[X 小时]
**文件**:[file1.ts, file2.tsx, ...]
**任务**:
- [ ] 任务 1
- [ ] 任务 2
- [ ] 任务 3
- [ ] 测试基本功能
**验证标准**:
- [ ] 具体测试 1
- [ ] 具体测试 2
- [ ] 具体测试 3
**退出标准**:[此阶段何时完成的明确定义]
---
## 阶段 2:[名称]
[... 重复结构 ...]
---
## 备注
**测试策略**:[每个阶段内联 / 单独的测试阶段 / 两者]
**部署策略**:[每个阶段部署 / 在里程碑部署 / 最终部署]
**上下文管理**:阶段大小适合单个会话并包含验证
# 数据库模式:[项目名称]
**数据库**:Cloudflare D1
**迁移**:位于 `migrations/`
**ORM**:[Drizzle / 原始 SQL / 无]
---
## 表
### `users`
**目的**:用户账户和认证
| 列名 | 类型 | 约束 | 备注 |
|--------|------|-------------|-------|
| id | INTEGER | PRIMARY KEY | 自增 |
| email | TEXT | UNIQUE, NOT NULL | 用于登录 |
| created_at | INTEGER | NOT NULL | Unix 时间戳 |
**索引**:
- `idx_users_email` 在 `email` 上(用于登录查找)
**关系**:
- 与 `tasks` 为一对多关系
---
### `tasks`
[... 重复结构 ...]
---
## 迁移
### 迁移 1:初始模式
**文件**:`migrations/0001_initial.sql`
**创建**:users, tasks 表
### 迁移 2:添加标签
**文件**:`migrations/0002_tags.sql`
**创建**:tags, task_tags 表
---
## 种子数据
用于开发,填充:
- 3 个示例用户
- 跨用户的 10 个示例任务
- 5 个标签
# API 端点:[项目名称]
**基础 URL**:`/api`
**认证**:Clerk JWT(带电子邮件和元数据的自定义模板)
**框架**:Hono(在 Cloudflare Workers 上)
---
## 认证
### POST /api/auth/verify
**目的**:验证 JWT 令牌
**认证**:无(公开)
**请求**:
```json
{
"token": "string"
}
响应 :
{ "valid": true, "email": "user@example.com" }{ "error": "Invalid token" }目的 : 获取当前用户资料 认证 : 必需(JWT) 响应 :
{ "id": 1, "email": "user@example.com", "created_at": 1234567890 }[... 为所有端点重复 ...]
所有端点返回以下格式的错误:
{
"error": "人类可读的消息",
"code": "ERROR_CODE",
"details": {} // 可选
}
标准代码 :
400: 错误请求(验证失败)
401: 未授权(未登录 / 无效令牌)
403: 禁止(权限不足)
404: 未找到
500: 内部服务器错误
# 架构:[项目名称]
**部署**:Cloudflare Workers
**前端**:Vite + React(作为静态资源提供)
**后端**:Worker 处理 API 路由
---
## 系统概览
┌─────────────────┐ │ 浏览器 │ └────────┬────────┘ │ ↓ HTTPS ┌─────────────────────────────────────┐ │ Cloudflare Worker │ │ ┌──────────────┐ ┌──────────────┐│ │ │ 静态资源 │ │ API 路由 ││ │ │ (Vite 构建) │ │ (Hono) ││ │ └──────────────┘ └───────┬──────┘│ └─────────────────────────────┼───────┘ │ ┌─────────────────┼─────────────────┐ ↓ ↓ ↓ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ D1 │ │ R2 │ │ Clerk │ │ (数据库)│ │(存储) │ │ (认证) │ └──────────┘ └──────────┘ └──────────┘
---
## 数据流
### 用户认证
1. 用户提交登录表单
2. 前端将凭据发送给 Clerk
3. Clerk 返回 JWT
4. 前端在 API 请求中包含 JWT
5. Worker 中间件验证 JWT
6. 受保护的路由可访问
### 任务创建
1. 用户提交任务表单
2. 前端使用 Zod 验证
3. POST /api/tasks 附带已验证的数据
4. Worker 再次进行服务器端验证
5. 插入到 D1 数据库
6. 返回创建的任务
7. 前端通过 TanStack Query 更新 UI
[... 根据需要添加更多流程 ...]
---
## 服务边界
**前端职责**:
- 用户交互
- 客户端验证
- 乐观更新
- 状态管理(TanStack Query + Zustand)
**Worker 职责**:
- 请求路由
- 认证/授权
- 服务器端验证
- 业务逻辑
- 数据库操作
- 第三方 API 调用
**Cloudflare 服务**:
- D1: 持久化关系型数据
- R2: 文件存储(图片、文档)
- KV: 配置、功能开关、缓存
---
## 安全
**认证**:带自定义声明的 Clerk JWT
**授权**:在变更前,中间件检查用户所有权
**输入验证**:客户端和服务器端都使用 Zod 模式
**CORS**:限制为生产域名
**密钥**:wrangler.jsonc 中的环境变量(不提交)
使用时机 : 项目使用 shadcn/ui 或需要组件规划
# UI 组件:[项目名称]
**框架**:shadcn/ui + Tailwind v4
**安装**:组件复制到 @/components/ui(完全可定制)
**策略**:根据需要按阶段安装组件(不一次性全部安装)
---
## 安装策略:按阶段
### 阶段 [N]:[阶段名称]([X] 个组件)
**时机**:在 [描述此阶段何时发生] 期间
**组件**:
- `button` - [此阶段中的具体用例]
- `input` - [具体用例]
- `card` - [具体用例]
[... 列出此阶段的所有组件 ...]
**安装**:
\`\`\`bash
pnpm dlx shadcn@latest add button input card [...]
\`\`\`
**用法**:[哪些路由/功能使用这些组件]
**重要注意事项**:
- [任何注意事项,例如:"使用 sonner 代替 toast 以获得更好的用户体验"]
- [组件特定的警告,例如:"data-table 对于 TanStack Table 集成至关重要"]
---
[为每个阶段重复...]
---
## 快速参考命令
### 最小可行产品安装(所有核心组件)
\`\`\`bash
pnpm dlx shadcn@latest add button input label card sonner [必需组件...]
\`\`\`
### 完整功能安装
\`\`\`bash
pnpm dlx shadcn@latest add button input [所有组件...]
\`\`\`
### 更新所有组件
\`\`\`bash
pnpm dlx shadcn@latest update
\`\`\`
---
## 按路由的组件使用情况
### [路由名称](`/route`)
- [使用的组件列表]
[为每个主要路由重复...]
---
## 设计决策
### [组件选择 1]
**推荐**:[选择的组件]
**原因**:[理由]
**考虑过的替代方案**:[评估过的其他选项]
**节省**:[如果适用,节省的时间/令牌]
[为每个重要的组件决策重复...]
---
## 组件数量细分
### 按类别
- **表单**:X 个组件([列表])
- **数据显示**:X 个组件([列表])
- **反馈**:X 个组件([列表])
- **布局**:X 个组件([列表])
- **导航**:X 个组件([列表])
### 按优先级
- **必需(最小可行产品)**:X 个组件
- **推荐**:X 个额外组件
- **可选(增强用户体验)**:X 个额外组件
---
## 安装清单
### 阶段 [N]:[名称] ✅
- [ ] component1
- [ ] component2
[...]
[为每个阶段重复...]
---
## 最佳实践
1. **根据需要安装** - 不要一次性安装所有组件。在实现功能时添加它们。
2. **安装后自定义** - 复制到 @/components/ui 的所有组件都是完全可定制的。
3. **保持组件更新** - 定期运行 \`pnpm dlx shadcn@latest update\`。
4. **检查新组件** - shadcn/ui 会定期添加新组件。
5. **暗黑模式自动工作** - 所有组件都遵循 Tailwind v4 主题。
6. **捆绑包大小优化** - 只包含已安装的组件 - 未使用的代码会被 tree-shaken 掉。
---
## 参考
- **shadcn/ui 文档**:https://ui.shadcn.com/docs/components
- **Tailwind v4 集成**:参见 \`tailwind-v4-shadcn\` 技能
- **组件安装**:https://ui.shadcn.com/docs/installation/vite
使用时机 : 用户提到复杂设置步骤或顺序敏感的工作流程
# 关键工作流程:[项目名称]
**目的**:记录非显而易见的设置步骤和顺序敏感的工作流程,以防止卡住
**日期**:[YYYY-MM-DD]
---
## ⚠️ [工作流程名称 1]([适用的阶段])
**停止!在 [开始 X] 之前阅读此部分。**
**上下文**:[为什么这个工作流程很棘手]
**顺序很重要**:
1. [步骤 1 包含具体命令/操作]
2. [步骤 2]
3. [步骤 3]
[...]
**为什么这个顺序**:[如果做错会有什么问题的解释]
**代码示例**:
\`\`\`bash
# 步骤 1:[描述]
[命令]
# 步骤 2:[描述]
[命令]
\`\`\`
**常见错误**:[人们通常做错什么]
**如果损坏如何修复**:[如何恢复]
---
## ⚠️ [工作流程名称 2]
[重复结构...]
---
## 快速清单
在开始每个阶段之前,检查是否有关键工作流程:
- [ ] 阶段 [N]:[工作流程名称](见上文)
- [ ] 阶段 [N+1]:无关键工作流程
- [ ] 阶段 [N+2]:[工作流程名称](见上文)
---
## 参考
- **[官方文档链接]**
- **[解释注意事项的 GitHub Issue 链接]**
- **[防止此问题的技能链接]**
使用时机 : 所有项目(推荐) - 节省大量时间
# 安装命令:[项目名称]
**目的**:每个阶段的复制粘贴命令(不再需要问"那个命令是什么来着?")
**日期**:[YYYY-MM-DD]
---
## 阶段 0:规划
[无 - 仅文档]
---
## 阶段 1:[阶段名称]
### 搭建项目
\`\`\`bash
npm create cloudflare@latest -- --framework=[framework]
cd [project-name]
\`\`\`
### 安装依赖
\`\`\`bash
pnpm add [packages]
pnpm add -D [dev-packages]
\`\`\`
### 初始化工具
\`\`\`bash
npx [tool] init
\`\`\`
### 验证设置
\`\`\`bash
pnpm dev
# 应该看到:[预期输出]
\`\`\`
---
## 阶段 2:[阶段名称]
[为每个阶段重复结构...]
---
## 数据库命令(阶段 [N])
### 创建数据库
\`\`\`bash
npx wrangler d1 create [db-name]
# 复制 database_id 并添加到 wrangler.jsonc 的 [[d1_databases]] 下
\`\`\`
### 运行迁移
\`\`\`bash
# 本地(开发)
npx wrangler d1 execute [db-name] --local --file=migrations/0001_initial.sql
# 生产环境
npx wrangler d1 execute [db-name] --remote --file=migrations/0001_initial.sql
\`\`\`
### 查询数据库
\`\`\`bash
# 本地
npx wrangler d1 execute [db-name] --local --command="SELECT * FROM users"
# 生产环境
npx wrangler d1 execute [db-name] --remote --command="SELECT * FROM users"
\`\`\`
---
## 部署命令
### 部署到 Cloudflare
\`\`\`bash
npm run build
npx wrangler deploy
\`\`\`
### 设置生产环境密钥
\`\`\`bash
npx wrangler secret put [SECRET_NAME]
# 提示时输入值
\`\`\`
### 检查部署
\`\`\`bash
npx wrangler tail
# 实时查看日志
\`\`\`
---
## 开发命令
### 启动开发服务器
\`\`\`bash
pnpm dev
\`\`\`
### 运行测试
\`\`\`bash
pnpm test
\`\`\`
### 代码检查和格式化
\`\`\`bash
pnpm lint
pnpm format
\`\`\`
---
## 故障排除命令
### 清除构建缓存
\`\`\`bash
rm -rf dist/ .wrangler/
pnpm dev
\`\`\`
### 检查 Wrangler 版本
\`\`\`bash
npx wrangler --version
# 应该是:[预期版本]
\`\`\`
### 验证绑定
\`\`\`bash
npx wrangler d1 list
npx wrangler r2 bucket list
\`\`\`
使用时机 : 项目需要 API 密钥或环境配置
# 环境变量:[项目名称]
**目的**:此项目所需的所有密钥、API 密钥和配置
**日期**:[YYYY-MM-DD]
---
## 开发环境 (.dev.vars)
**文件**:\`.dev.vars\`(本地文件,**不**提交到 git)
\`\`\`bash
# 认证
CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
# 数据库
DATABASE_URL=local
# API 密钥
[SERVICE]_API_KEY=[value]
# 功能开关
ENABLE_[FEATURE]=true
\`\`\`
**如何获取这些密钥**:
1. **Clerk 密钥**:https://dashboard.clerk.com → API Keys
2. **[其他服务]**:[获取步骤]
---
## 生产环境 (wrangler.jsonc 密钥)
**密钥(通过 CLI 设置)**:
\`\`\`bash
# 通过以下方式设置:npx wrangler secret put SECRET_NAME
CLERK_SECRET_KEY=sk_live_...
[SERVICE]_API_KEY=[production-value]
\`\`\`
**绑定(在 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]"
}
]
}
\`\`\`
---
## 环境变量参考
| 变量 | 必需 | 使用位置 | 备注 |
|----------|----------|------------|-------|
| CLERK_PUBLISHABLE_KEY | 是 | 前端 | 公开,在示例文件中提交是安全的 |
| CLERK_SECRET_KEY | 是 | Worker | **密钥** - 绝不提交 |
| DATABASE_URL | 仅本地 | 开发 | 指向本地 .wrangler/state |
| [OTHER_VAR] | [是/否] | [位置] | [备注] |
---
## 设置清单
### 本地开发
- [ ] 在项目根目录创建 \`.dev.vars\`
- [ ] 将 \`.dev.vars\` 添加到 \`.gitignore\`(应该已经存在)
- [ ] 从 \`.dev.vars.example\` 复制值(如果存在)
- [ ] 从服务获取 API 密钥(上面的链接)
- [ ] 运行 \`pnpm dev\` 进行验证
### 生产环境部署
- [ ] 通过 \`npx wrangler secret put\` 设置所有密钥
- [ ] 在 \`wrangler.jsonc\` 中配置所有绑定
- [ ] 部署:\`npx wrangler deploy\`
- [ ] 验证密钥已设置:\`npx wrangler secret list\`
- [ ] 测试生产环境部署
---
## 安全注意事项
**绝不提交**:
- \`.dev.vars\`
- 任何包含实际密钥值的文件
- 生产环境 API 密钥
**可以安全提交**:
- \`.dev.vars.example\`(带占位符值)
- \`wrangler.jsonc\`(绑定配置,**不是**密钥值)
- 公钥(Clerk publishable key 等)
**如果密钥泄露**:
1. 立即轮换所有受影响的密钥
2. 更新生产环境密钥:\`npx wrangler secret put [KEY]\`
3. 在服务仪表板中撤销旧密钥
4. 检查 git 历史记录中是否有泄露的密钥
---
## 参考
- **Cloudflare 密钥**:https://developers.cloudflare.com/workers/configuration/secrets/
- **Wrangler 配置**:https://developers.cloudflare.com/workers/wrangler/configuration/
- **[服务] API 文档**:[链接]
始终生成此文件 - 用于跟踪进度
# 会话状态
**当前阶段**:阶段 0(规划)
**当前状态**:规划中
**最后检查点**:尚无
**规划文档**:\`docs/IMPLEMENTATION_PHASES.md\`, \`docs/CRITICAL_WORKFLOWS.md\`(如果存在)
---
## 阶段 0:规划 ✅
**完成时间**:[YYYY-MM-DD]
**摘要**:规划文档已创建
**交付物**:[列出生成的文档]
## 阶段 1:[名称] ⏸️
**规范**:\`docs/IMPLEMENTATION_PHASES.md#phase-1\`
**类型**:[基础设施/数据库/API/UI/集成]
**时间**:[X 小时]
**进度**:未开始
**下一步操作**:[具体文件 + 行号 + 要做什么]
## 阶段 2:[名称] ⏸️
**规范**:\`docs/IMPLEMENTATION_PHASES.md#phase-2\`
**类型**:[类型]
**时间**:[X 小时]
**进度**:未开始
[将剩余阶段折叠为每阶段 2-3 行...]
---
## 重要提醒
**开始前**:
- [ ] 阅读 \`docs/CRITICAL_WORKFLOWS.md\`(如果存在)
- [ ] 查看 \`docs/INSTALLATION_COMMANDS.md\` 中的阶段命令
- [ ] 检查 \`docs/ENV_VARIABLES.md\` 中的必需密钥
**关键工作流程**:
[如果存在,链接到 CRITICAL_WORKFLOWS.md 中的具体工作流程]
---
## 已知风险
**高风险阶段**:
- 阶段 [N]:[名称] - [为什么有风险]
- 阶段 [N+1]:[名称] - [为什么有风险]
**缓解措施**:[策略]
---
**状态图例**:⏸️ 待处理 | 🔄 进行中 | ✅ 完成 | 🚫 阻塞 | ⚠️ 问题
目的 : 帮助 Claude 通过文件映射、数据流图和注意事项来导航代码。
包含于 : API、UI、集成阶段(基础设施、数据库、测试阶段可选)
### 文件映射
- `src/routes/tasks.ts` (~150 行) - CRUD 端点
- 目的,关键导出,依赖项,被谁使用
- `src/lib/schemas.ts` (~80 行) - 验证模式
- `src/middleware/auth.ts`(现有,无更改)
使用 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
\`\`\`
**内部**:auth.ts, schemas.ts, D1 绑定
**外部**:zod, hono, @clerk/backend
**配置**:CLERK_SECRET_KEY
**绑定**:DB (D1)
**注意事项**:
- 所有权验证(PATCH/DELETE 必须检查 user_id)
- 需要分页(每页最多 50 条)
- 软删除(deleted_at,不是 DELETE FROM)
- UTC 时间戳(仅在前端转换)
## 阶段 3:任务 API
**类型**:API | **预计**:4 小时
**文件**:src/routes/tasks.ts, src/lib/schemas.ts, src/middleware/auth.ts(修改)
### 文件映射
- src/routes/tasks.ts (~150 行) - CRUD 端点
- src/lib/schemas.ts (+40 行) - 验证模式
### 数据流
\`\`\`mermaid
sequenceDiagram
Client->>Worker: POST /api/tasks
Worker->>Auth: authenticateUser()
Worker->>D1: INSERT
D1->>Worker: task
Worker->>Client: 201
\`\`\`
### 依赖项和注意事项
**内部**:auth.ts, schemas.ts, D1
**外部**:zod, hono, @clerk/backend
**注意事项**:所有权检查,分页(最多 50 条),软删除,UTC 时间戳
### 任务
- [ ] 创建模式
- [ ] GET /api/tasks(分页)
- [ ] POST /api/tasks(已验证)
- [ ] PATCH /api/tasks/:id(所有权检查)
- [ ] DELETE /api/tasks/:id(软删除)
### 验证
- [ ] GET 返回 200 + 数组
- [ ] POST 有效→201,无效→400
- [ ] PATCH 检查所有权(如果用户错误则返回 403)
- [ ] DELETE 设置 deleted_at
Specialized planning assistant for web application projects. Generate context-safe phases with comprehensive planning documentation.
Two slash commands are available to automate project planning workflows:
/plan-projectAutomates planning for NEW projects: generates IMPLEMENTATION_PHASES.md + SESSION.md + git commit.
/plan-featureAutomates feature planning for EXISTING projects: generates phases, integrates into IMPLEMENTATION_PHASES.md, updates SESSION.md.
You generate planning documentation for web app projects:
Unless the user specifies otherwise, assume this preferred stack (from their CLAUDE.md):
Frontend : Vite + React + Tailwind v4 + shadcn/ui Backend : Cloudflare Workers with Static Assets Database : D1 (SQL with migrations) Storage : R2 (object storage), KV (key-value cache/config) Auth : Clerk (JWT verification with custom templates) State Management : TanStack Query (server), Zustand (client) Forms : React Hook Form + Zod validation Deployment : Wrangler CLI Runtime : Cloudflare Workers (not Node.js)
Only ask about stack choices when:
Extract: core functionality, user interactions, data model, integrations, complexity signals.
Focus on: Auth, Data, Features, Integrations, Scope
Example :
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?
Always :
Conditional (ask user):
Create structured phases using these types:
When : Project start, deployment setup Scope : Scaffolding, build config, initial deployment Files : 3-5 (package.json, wrangler.jsonc, vite.config.ts, etc) Duration : 1-3 hours Verification : Dev server runs, can deploy, basic "Hello World" works
When : Data model setup, schema changes Scope : Migrations, schema definition, seed data Files : 2-4 (migration files, schema types) Duration : 2-4 hours Verification : CRUD works, constraints enforced, relationships correct
When : Backend endpoints needed Scope : Routes, middleware, validation, error handling Files : 3-6 (route files, middleware, schemas) Duration : 3-6 hours (per endpoint group) Verification : All HTTP methods tested (200, 400, 401, 500), CORS works
When : User interface components Scope : Components, forms, state, styling Files : 4-8 (component files) Duration : 4-8 hours (per feature) Verification : User flows work, forms validate, states update, responsive
When : Third-party services (auth, payments, AI, etc) Scope : API setup, webhooks, configuration Files : 2-4 (integration files, middleware) Duration : 3-5 hours (per integration) Verification : Service works, webhooks fire, errors handled
When : Need formal test suite (optional) Scope : E2E tests, integration tests Files : Test files Duration : 3-6 hours Verification : Tests pass, coverage meets threshold
Every phase you generate MUST follow these constraints:
Every phase MUST have:
If a phase violates sizing rules, automatically suggest splitting:
⚠️ 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: [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: [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: [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"
}
Responses :
{ "valid": true, "email": "user@example.com" }{ "error": "Invalid token" }Purpose : Get current user profile Auth : Required (JWT) Responses :
{ "id": 1, "email": "user@example.com", "created_at": 1234567890 }[... repeat for all endpoints ...]
All endpoints return errors in this format:
{
"error": "Human-readable message",
"code": "ERROR_CODE",
"details": {} // optional
}
Standard Codes :
400: Bad request (validation failed)
401: Unauthorized (not logged in / invalid token)
403: Forbidden (insufficient permissions)
404: Not found
500: Internal server error
# Architecture: [Project Name]
**Deployment**: Cloudflare Workers
**Frontend**: Vite + React (served as static assets)
**Backend**: Worker handles API routes
---
## System Overview
┌─────────────────┐ │ Browser │ └────────┬────────┘ │ ↓ HTTPS ┌─────────────────────────────────────┐ │ Cloudflare Worker │ │ ┌──────────────┐ ┌──────────────┐│ │ │ Static Assets│ │ API Routes ││ │ │ (Vite build) │ │ (Hono) ││ │ └──────────────┘ └───────┬──────┘│ └─────────────────────────────┼───────┘ │ ┌─────────────────┼─────────────────┐ ↓ ↓ ↓ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ D1 │ │ R2 │ │ Clerk │ │ (Database)│ │(Storage) │ │ (Auth) │ └──────────┘ └──────────┘ └──────────┘
---
## 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)
Use when : Project uses shadcn/ui OR needs component planning
# 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
Use when : User mentioned complex setup steps OR order-sensitive workflows
# 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]**
Use when : All projects (recommended) - saves massive time
# 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
\`\`\`
Use when : Project needs API keys OR environment configuration
# 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]
Always generate this - for tracking progress
# 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
Purpose : Help Claude navigate code with file maps, data flow diagrams, and gotchas.
Include for : API, UI, Integration phases (optional for Infrastructure, Database, Testing)
### 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)
Use Mermaid for sequence diagrams (API), flowcharts (UI), architecture diagrams:
\`\`\`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.
✅ Every phase : Type, time, files, tasks, verification, exit criteria ✅ Context-safe : ≤8 files, ≤2 dependencies, fits in 2-4hr session ✅ Verification specific : "valid login→200+token, invalid→401" not "test feature" ✅ Exit criteria clear : "All endpoints correct status codes" not "API done" ✅ Logical order : Infrastructure→Database→API→UI→Integration→Testing ✅ Realistic estimates : Include implementation+verification+fixes
Generate docs immediately after user confirms. Present as markdown files or code blocks.
Include: Full IMPLEMENTATION_PHASES.md + conditional docs (DATABASE_SCHEMA.md, API_ENDPOINTS.md, etc.) + Summary (phases, duration, deployment strategy, docs created)
Planning assistant - Structure work into manageable, context-safe phases with clear verification.
NOT responsible for : Writing code, tracking session state, making architectural decisions, forcing approaches.
Weekly Installs
576
Repository
GitHub Stars
643
First Seen
Jan 20, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
claude-code422
opencode396
gemini-cli376
codex352
cursor312
antigravity308
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
136,300 周安装
OpenAPI 转 TypeScript 工具 - 自动生成 API 接口与类型守卫
563 周安装
数据库模式设计器 - 内置最佳实践,自动生成生产级SQL/NoSQL数据库架构
564 周安装
Rust Unsafe代码检查器 - 安全使用Unsafe Rust的完整指南与最佳实践
564 周安装
.NET并发编程模式指南:async/await、Channels、Akka.NET选择决策树
565 周安装
韩语语法检查器 - 基于国立国语院标准的拼写、空格、语法、标点错误检测与纠正
565 周安装
技能安全扫描器 - 检测Claude技能安全漏洞,防范提示注入与恶意代码
565 周安装