36c - 第2周：设计与开发启动

AI 设计的核心优势：
├── 速度：从文字描述到高保真原型只需 5-15 分钟
├── 一致性：AI 生成的组件自动遵循设计规范
├── 全状态覆盖：提醒 AI 生成空状态、加载、错误、成功等所有状态
├── 代码就绪：v0.dev 等工具直接输出可用的 React 代码
└── 迭代快速：不满意？修改 prompt 重新生成，成本几乎为零

MVP 页面清单模板：

□ 公开页面（无需登录）：
  ├── Landing Page（首页/营销页）
  ├── 定价页
  ├── 登录/注册页
  └── 404 页面

□ 核心功能页面（需登录）：
  ├── Dashboard（仪表板/主页）
  ├── [核心功能页面 1]
  ├── [核心功能页面 2]
  ├── [核心功能页面 3]
  └── 设置页

□ 每个页面需要覆盖的状态：
  ├── 空状态（Empty State）：首次使用，没有数据
  ├── 加载状态（Loading State）：数据加载中
  ├── 成功状态（Success State）：正常显示数据
  ├── 错误状态（Error State）：请求失败或数据异常
  └── 边界状态：数据过多、数据过少、长文本溢出

提示词模板 1：v0.dev Landing Page 设计

请生成一个现代化的 SaaS Landing Page，要求如下：

产品名称：[名称]
一句话描述：[产品做什么]
目标用户：[用户画像]
主色调：[颜色，如 blue-600]
风格：简洁现代、专业可信

页面结构：
1. **导航栏**：Logo + 产品名 + 功能/定价/文档链接 + 登录/注册按钮
2. **Hero Section**：
   - 大标题（一句话说清价值主张）
   - 副标题（2 行补充说明）
   - 主 CTA 按钮（"免费开始" / "Start Free"）
   - 次 CTA 按钮（"查看演示"）
   - Hero 图片/截图占位区域
3. **痛点区域**：3 个用户痛点卡片（图标 + 标题 + 描述）
4. **功能展示**：3-5 个核心功能（左右交替布局，图标 + 标题 + 描述 + 截图占位）
5. **社会证明**：用户评价卡片（3 个，头像 + 姓名 + 职位 + 评价）
6. **定价表**：Free / Pro / Enterprise 三栏定价
7. **FAQ**：5 个常见问题（手风琴展开）
8. **底部 CTA**：再次邮件收集 + CTA 按钮
9. **Footer**：链接分组 + 社交媒体图标 + 版权信息

技术要求：
- 使用 shadcn/ui 组件
- Tailwind CSS 样式
- 支持深色/浅色主题
- 完全响应式（移动端优先）
- 包含平滑滚动动画

提示词模板 2：Dashboard 页面设计

请生成一个 SaaS Dashboard 页面，要求如下：

产品：[产品描述]
用户角色：[用户画像]
Dashboard 需要展示的信息：
- [关键指标 1，如"今日审查数"]
- [关键指标 2，如"发现的问题数"]
- [关键指标 3，如"代码质量评分"]
- [最近活动列表]
- [快捷操作按钮]

页面结构：
1. **顶部导航**：Logo + 搜索框 + 通知铃铛 + 用户头像下拉菜单
2. **侧边栏**：导航菜单（Dashboard/[功能1]/[功能2]/设置）+ 折叠按钮
3. **主内容区**：
   a. 欢迎横幅（"Good morning, [用户名]"）
   b. 关键指标卡片（4 个，带趋势箭头和迷你图表）
   c. 最近活动表格（时间/操作/状态/详情链接）
   d. 快捷操作区域（2-3 个常用操作按钮）

请同时生成以下状态的变体：

**空状态**（新用户首次登录）：
- 指标卡片显示 "—" 或 0
- 活动列表显示引导插画 + "开始你的第一个 [操作]" CTA
- 包含新手引导步骤（1-2-3 步骤卡片）

**加载状态**：
- 指标卡片显示 Skeleton 骨架屏
- 表格显示 Skeleton 行
- 使用 shadcn/ui 的 Skeleton 组件

**错误状态**：
- 数据加载失败时显示错误提示卡片
- 包含"重试"按钮
- 友好的错误消息（不显示技术细节）

技术要求：
- 使用 shadcn/ui 组件（Card, Table, Badge, Skeleton, Alert）
- 响应式：移动端侧边栏变为底部导航或汉堡菜单
- 支持深色/浅色主题

提示词模板 3：核心功能页面设计

请生成 [功能名称] 页面，要求如下：

功能描述：[详细描述这个功能做什么]
用户流程：
1. 用户 [操作1]
2. 系统 [响应1]
3. 用户 [操作2]
4. 系统 [响应2]

页面布局：
- [描述页面的主要区域和布局]

交互要求：
- [描述关键交互，如表单提交、列表筛选、拖拽排序等]

请覆盖以下状态：
1. 正常状态：有数据时的完整展示
2. 空状态：没有数据时的引导
3. 加载状态：数据加载中的骨架屏
4. 错误状态：操作失败时的提示
5. 成功状态：操作成功后的反馈（Toast 通知）

技术要求：
- 使用 shadcn/ui 组件
- 表单使用 react-hook-form + zod 验证
- 包含适当的加载和错误处理 UI

提示词模板 4：认证页面设计

请生成登录和注册页面，要求如下：

认证方式：
- 邮箱 + 密码登录/注册
- OAuth 登录（GitHub / Google）
- 忘记密码流程

登录页面：
- 左侧：产品介绍/品牌图片
- 右侧：登录表单
  ├── 邮箱输入框
  ├── 密码输入框（带显示/隐藏切换）
  ├── "记住我" 复选框
  ├── "忘记密码？" 链接
  ├── 登录按钮
  ├── 分隔线 "或"
  ├── GitHub 登录按钮
  ├── Google 登录按钮
  └── "没有账号？注册" 链接

注册页面：
- 类似布局，表单包含：
  ├── 用户名输入框
  ├── 邮箱输入框
  ├── 密码输入框（带强度指示器）
  ├── 确认密码输入框
  ├── 服务条款复选框
  └── 注册按钮

错误状态：
- 邮箱格式错误
- 密码不符合要求（实时验证提示）
- 邮箱已注册
- OAuth 登录失败

技术要求：
- 使用 shadcn/ui 组件（Input, Button, Checkbox, Label）
- 表单验证使用 zod schema
- 响应式：移动端全宽表单
- 支持深色/浅色主题

全状态设计矩阵：

| 状态 | 描述 | 设计要点 | 常见遗漏 |
|------|------|---------|---------|
| 空状态 | 首次使用，无数据 | 引导插画 + 行动号召 | 只显示空白页面 |
| 加载状态 | 数据请求中 | Skeleton 骨架屏 | 无反馈或只有 spinner |
| 成功状态 | 正常数据展示 | 清晰的信息层次 | 数据过多时布局崩溃 |
| 错误状态 | 请求失败 | 友好提示 + 重试按钮 | 显示技术错误信息 |
| 部分加载 | 部分数据成功 | 成功部分正常显示 | 全部失败或全部成功 |
| 离线状态 | 网络断开 | 离线提示 + 缓存数据 | 无任何提示 |
| 权限不足 | 无权访问 | 403 页面 + 升级引导 | 显示空白或报错 |
| 长列表 | 数据量大 | 分页/虚拟滚动 | 一次加载全部数据 |
| 长文本 | 内容超长 | 截断 + "查看更多" | 文本溢出破坏布局 |

提示词模板 5：全状态设计审查

请审查以下页面设计，检查是否覆盖了所有必要的 UI 状态：

页面描述：[描述页面功能]
当前设计：[粘贴当前设计代码或描述]

请检查以下状态是否都有对应的 UI 处理：

1. **空状态**：用户首次访问，没有任何数据
   - 是否有引导性的空状态插画或文案？
   - 是否有明确的行动号召（CTA）？

2. **加载状态**：数据正在从服务器获取
   - 是否使用了 Skeleton 骨架屏（而非简单的 spinner）？
   - 骨架屏的形状是否与实际内容匹配？

3. **错误状态**：API 请求失败
   - 错误消息是否用户友好（非技术语言）？
   - 是否提供了重试按钮？
   - 是否区分了不同类型的错误（网络/服务器/权限）？

4. **成功反馈**：用户操作成功
   - 是否有 Toast 通知或其他成功反馈？
   - 反馈是否在合理时间后自动消失？

5. **表单验证**：用户输入不合法
   - 是否有实时验证（输入时）？
   - 错误提示是否紧邻对应的输入框？
   - 提交按钮在表单无效时是否禁用？

6. **边界情况**：
   - 长文本是否正确截断？
   - 大量数据是否有分页或虚拟滚动？
   - 图片加载失败是否有 fallback？

请列出缺失的状态，并为每个缺失状态提供设计建议。

Day 1 设计产出清单：

□ Landing Page 完整设计（含移动端适配）
□ 登录/注册页面设计
□ Dashboard 页面设计（含空/加载/错误/成功 4 种状态）
□ 核心功能页面 1 设计（含全状态）
□ 核心功能页面 2 设计（含全状态）
□ 核心功能页面 3 设计（含全状态）
□ 设置页面设计
□ 404 页面设计

组织方式：
├── 方案 A：v0.dev 项目中保存所有生成结果（推荐）
│   └── 每个页面一个 v0 对话，方便后续迭代
├── 方案 B：导出代码到本地项目的 /design 目录
│   └── 作为参考，开发时逐步集成
└── 方案 C：截图保存到 Figma/Notion
    └── 作为视觉参考文档

提示词模板 6：设计风格指南生成

基于以下产品信息，生成一份简洁的设计风格指南：

产品名称：[名称]
产品类型：[SaaS/工具/平台]
目标用户：[用户画像]
品牌调性：[专业/友好/极简/活力/科技感]

请生成：

1. **配色方案**：
   - 主色（Primary）：用于 CTA 按钮、重要链接
   - 次色（Secondary）：用于次要操作、标签
   - 强调色（Accent）：用于通知、高亮
   - 成功/警告/错误/信息色
   - 中性色阶（背景、文字、边框）
   - 提供 HSL 值（适配 shadcn/ui 的 CSS 变量格式）

2. **字体方案**：
   - 标题字体
   - 正文字体
   - 代码字体（如适用）
   - 字号层级（h1-h6, body, small, caption）

3. **间距系统**：
   - 基础间距单位
   - 组件内间距
   - 组件间间距
   - 页面边距

4. **圆角规范**：
   - 按钮圆角
   - 卡片圆角
   - 输入框圆角
   - 头像圆角

5. **阴影层级**：
   - 卡片阴影
   - 下拉菜单阴影
   - 模态框阴影

请以 CSS 变量格式输出，兼容 shadcn/ui 的主题系统。

Solo Founder 的设计系统 ≠ 大公司的设计系统

大公司：Figma 组件库 + Storybook + 设计文档 + 设计评审流程
Solo Founder：CSS 变量 + shadcn/ui 主题配置 + 简单的风格指南

你需要的是"刚好够用"的设计系统，不是完美的设计系统。

提示词模板 7：设计一致性审查

请审查以下页面设计的一致性：

[粘贴所有页面的设计代码或截图描述]

审查维度：

1. **颜色一致性**：
   - 所有页面是否使用相同的主色/次色/强调色？
   - 状态颜色（成功/警告/错误）是否统一？
   - 背景色和文字色是否一致？

2. **排版一致性**：
   - 标题层级（h1-h6）的字号是否统一？
   - 正文字号和行高是否一致？
   - 字体粗细使用是否规范？

3. **间距一致性**：
   - 卡片内间距是否统一？
   - 组件间距是否遵循统一的间距系统？
   - 页面边距是否一致？

4. **组件一致性**：
   - 按钮样式（大小、圆角、颜色）是否统一？
   - 输入框样式是否统一？
   - 卡片样式是否统一？
   - 表格样式是否统一？

5. **交互一致性**：
   - Hover 效果是否统一？
   - 加载状态的表现是否统一？
   - 错误提示的方式是否统一？

6. **响应式一致性**：
   - 断点是否统一（sm/md/lg/xl）？
   - 移动端布局策略是否一致？

请列出所有不一致的地方，并建议统一方案。

提示词模板 8：可用性审查

请从用户体验角度审查以下页面设计：

[粘贴页面设计代码或描述]

审查维度：

1. **信息层次**：
   - 用户能否在 3 秒内理解页面的主要功能？
   - 最重要的信息是否最突出？
   - 视觉层次是否清晰（标题 > 副标题 > 正文 > 辅助信息）？

2. **操作效率**：
   - 核心操作是否在 3 次点击内完成？
   - CTA 按钮是否足够醒目？
   - 常用操作是否有快捷方式？

3. **认知负荷**：
   - 页面信息是否过多？
   - 是否有不必要的选项或功能？
   - 表单字段是否可以减少？

4. **错误预防**：
   - 危险操作（删除、取消）是否有确认步骤？
   - 表单是否有实时验证？
   - 是否有撤销功能？

5. **无障碍基础**：
   - 颜色对比度是否足够（WCAG AA 标准，4.5:1）？
   - 是否仅依赖颜色传达信息？
   - 交互元素是否有足够的点击区域（至少 44×44px）？

6. **移动端体验**：
   - 触摸目标是否足够大？
   - 是否有不适合移动端的交互（如 hover 依赖）？
   - 表单在移动端是否易于填写？

请为每个问题给出 1-5 分评分，并提供改进建议。

修复优先级：
├── P0（必须修复）：颜色对比度不足、核心操作不明显、缺少错误状态
├── P1（应该修复）：间距不一致、组件样式不统一、移动端布局问题
├── P2（可以延后）：动画效果、微交互、边缘情况的 UI
└── 原则：P0 今天修复，P1 开发时修复，P2 上线后迭代

提示词模板 9：CSS 变量 / Design Token 生成

基于以下设计风格指南，生成完整的 CSS 变量文件：

配色方案：[粘贴之前生成的配色方案]
字体方案：[字体选择]
间距系统：[间距规范]

请生成 globals.css 文件，包含：

1. **颜色变量**（HSL 格式，兼容 shadcn/ui）：
   ```css
   :root {
     --background: 0 0% 100%;
     --foreground: 222.2 84% 4.9%;
     --card: 0 0% 100%;
     --card-foreground: 222.2 84% 4.9%;
     --popover: 0 0% 100%;
     --popover-foreground: 222.2 84% 4.9%;
     --primary: [主色 HSL];
     --primary-foreground: [主色前景 HSL];
     --secondary: [次色 HSL];
     --secondary-foreground: [次色前景 HSL];
     --muted: [柔和色 HSL];
     --muted-foreground: [柔和前景 HSL];
     --accent: [强调色 HSL];
     --accent-foreground: [强调前景 HSL];
     --destructive: [危险色 HSL];
     --destructive-foreground: [危险前景 HSL];
     --border: [边框色 HSL];
     --input: [输入框边框 HSL];
     --ring: [焦点环 HSL];
     --radius: 0.5rem;
   }

   .dark {
     /* 深色主题对应变量 */
   }

#### 步骤 5：选择和配置组件库（30 分钟）

Solo Founder 的组件库选择标准：AI 友好、可定制、零运行时依赖。

shadcn/ui 初始化配置：

```bash
# 在 Next.js 项目中初始化 shadcn/ui
npx shadcn@latest init

# 选择配置：
# Style: Default
# Base color: 根据你的设计选择
# CSS variables: Yes（重要！启用 CSS 变量模式）

# 安装常用组件
npx shadcn@latest add button card input label
npx shadcn@latest add dialog dropdown-menu select
npx shadcn@latest add table badge skeleton toast
npx shadcn@latest add form tabs alert avatar
npx shadcn@latest add sheet separator scroll-area

提示词模板 10：设计系统文档生成

基于以下配置，生成一份简洁的设计系统文档（Markdown 格式）：

CSS 变量文件：[粘贴 globals.css]
组件库：shadcn/ui
技术栈：Next.js + TypeScript + Tailwind CSS

请生成 docs/design-system.md，包含：

1. **配色方案**：
   - 颜色色板（列出所有颜色及其用途）
   - 使用规则（什么场景用什么颜色）
   - 深色主题对应关系

2. **排版规范**：
   - 字体层级表（标签/字号/行高/字重/用途）
   - 使用示例

3. **间距规范**：
   - 间距值表
   - 使用场景（组件内/组件间/页面边距）

4. **组件使用规范**：
   - 按钮：变体（primary/secondary/outline/ghost/destructive）和使用场景
   - 输入框：变体和验证状态
   - 卡片：使用场景和内容结构
   - 表格：列对齐、排序、分页规范
   - Toast：类型（success/error/warning/info）和持续时间

5. **布局规范**：
   - 页面最大宽度
   - 网格系统
   - 响应式断点
   - 侧边栏宽度

6. **图标规范**：
   - 图标库（Lucide Icons）
   - 图标大小（sm/md/lg）
   - 使用规则

这份文档将作为 AI 编码时的上下文参考，
确保后续生成的代码风格一致。

提示词模板 11：Tailwind 配置生成

基于以下设计系统，生成 tailwind.config.ts 的自定义配置：

设计系统：[粘贴设计系统文档]

请生成 tailwind.config.ts，包含：

1. **颜色扩展**：映射 CSS 变量到 Tailwind 类名
2. **字体扩展**：自定义字体族
3. **间距扩展**：自定义间距值（如果默认不够用）
4. **动画扩展**：常用动画（fade-in, slide-up, scale-in）
5. **屏幕断点**：确认或自定义断点
6. **插件**：tailwindcss-animate（shadcn/ui 需要）

同时生成 components.json（shadcn/ui 配置文件），确保：
- style: "default"
- tailwind.cssVariables: true
- aliases 配置正确

Day 2 结束时，你应该有以下产出：

□ 设计审查报告（一致性 + 可用性问题列表）
□ 修复后的设计稿（P0 问题已修复）
□ CSS 变量文件（globals.css，含浅色/深色主题）
□ Tailwind 配置文件（tailwind.config.ts）
□ shadcn/ui 配置和常用组件安装
□ 设计系统文档（docs/design-system.md）
□ 组件库选择决策记录

这些产出将确保 Day 3-5 的开发工作风格一致、效率最高。

Day 3-5 的核心目标：
├── 项目初始化：创建项目骨架，配置开发环境
├── CI/CD 配置：自动化构建和部署流水线
├── Steering 配置：确保 AI 编码的一致性
├── MCP 配置：连接必要的外部服务
├── 核心模块 v1：完成 1-2 个核心模块的基础实现
└── 输出：可运行的项目骨架 + 核心模块 v1

注意：不要试图在 3 天内完成所有功能！
核心开发将在 Week 3-4 通过 Spec-Driven 工作流系统化推进。

# 方案 A：标准 Next.js 项目（推荐）
pnpm create next-app@latest my-saas \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"
 
cd my-saas
 
# 方案 B：T3 Stack（如果需要 tRPC + Prisma）
pnpm create t3-app@latest my-saas
 
# 方案 C：Tauri 桌面应用
pnpm create tauri-app my-desktop-app \
  --template react-ts

提示词模板 12：项目依赖清单生成

基于以下技术栈和功能需求，生成项目依赖清单：

技术栈：Next.js 15 + TypeScript + Tailwind CSS + shadcn/ui
数据库：Supabase
认证：Supabase Auth
支付：Stripe
邮件：Resend
功能需求：[MVP 功能列表]

请分类列出需要安装的依赖：

1. **核心依赖**（dependencies）：
   - UI 相关
   - 数据获取相关
   - 认证相关
   - 表单验证相关
   - 工具库

2. **开发依赖**（devDependencies）：
   - 类型定义
   - 测试框架
   - 代码质量工具

3. **安装命令**：
   ```bash
   # 核心依赖
   pnpm add [依赖列表]
   
   # 开发依赖
   pnpm add -D [依赖列表]

常用依赖安装示例（Web SaaS）：

```bash
# UI 组件（shadcn/ui 已在 Day 2 初始化）
# 表单验证
pnpm add zod react-hook-form @hookform/resolvers

# Supabase
pnpm add @supabase/supabase-js @supabase/ssr

# Stripe（如需支付）
pnpm add stripe @stripe/stripe-js

# 邮件（如需发送邮件）
pnpm add resend @react-email/components

# 工具库
pnpm add date-fns clsx tailwind-merge lucide-react

# 开发依赖
pnpm add -D @types/node vitest @vitejs/plugin-react
pnpm add -D @playwright/test

提示词模板 13：项目目录结构生成

基于以下技术栈，生成推荐的项目目录结构：

技术栈：Next.js 15 App Router + TypeScript + Tailwind CSS + shadcn/ui
数据库：Supabase
功能模块：[列出 MVP 功能模块]

请生成目录结构，遵循以下原则：
- 按功能模块组织（Feature-based），不按技术层组织
- 共享组件放在 components/ui/（shadcn/ui 组件）
- 业务组件放在对应功能目录下
- Server Actions 放在对应功能目录的 actions.ts 中
- 类型定义放在对应功能目录的 types.ts 中

示例结构：

src/
├── app/                          # Next.js App Router
│   ├── (auth)/                   # 认证相关页面（分组路由）
│   │   ├── login/page.tsx
│   │   ├── register/page.tsx
│   │   └── layout.tsx
│   ├── (dashboard)/              # 需登录的页面（分组路由）
│   │   ├── dashboard/page.tsx
│   │   ├── [feature1]/page.tsx
│   │   ├── [feature2]/page.tsx
│   │   ├── settings/page.tsx
│   │   └── layout.tsx            # 含侧边栏的布局
│   ├── api/                      # API Routes（Webhook 等）
│   │   └── webhook/route.ts
│   ├── layout.tsx                # 根布局
│   ├── page.tsx                  # Landing Page
│   └── globals.css               # 全局样式 + CSS 变量
├── components/
│   ├── ui/                       # shadcn/ui 组件（自动生成）
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   └── ...
│   ├── layout/                   # 布局组件
│   │   ├── header.tsx
│   │   ├── sidebar.tsx
│   │   └── footer.tsx
│   └── shared/                   # 共享业务组件
│       ├── empty-state.tsx
│       ├── loading-skeleton.tsx
│       └── error-boundary.tsx
├── features/                     # 功能模块（核心！）
│   ├── auth/                     # 认证模块
│   │   ├── components/
│   │   ├── actions.ts            # Server Actions
│   │   ├── hooks.ts              # 自定义 Hooks
│   │   └── types.ts              # 类型定义
│   ├── [feature1]/               # 功能模块 1
│   │   ├── components/
│   │   ├── actions.ts
│   │   ├── hooks.ts
│   │   └── types.ts
│   └── [feature2]/               # 功能模块 2
│       ├── components/
│       ├── actions.ts
│       ├── hooks.ts
│       └── types.ts
├── lib/                          # 工具库
│   ├── supabase/
│   │   ├── client.ts             # 浏览器端 Supabase 客户端
│   │   ├── server.ts             # 服务端 Supabase 客户端
│   │   └── middleware.ts         # 认证中间件
│   ├── stripe.ts                 # Stripe 配置
│   ├── utils.ts                  # 通用工具函数（cn 等）
│   └── constants.ts              # 常量定义
├── types/                        # 全局类型定义
│   └── index.ts
└── middleware.ts                  # Next.js 中间件（认证守卫）

# .env.local（本地开发，不提交到 Git）

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# Stripe（如需支付）
STRIPE_SECRET_KEY=sk_test_xxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

# Resend（如需邮件）
RESEND_API_KEY=re_xxx

# 应用配置
NEXT_PUBLIC_APP_URL=http://localhost:3000

# .env.example（提交到 Git，作为模板）

# Supabase
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# Stripe
STRIPE_SECRET_KEY=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
STRIPE_WEBHOOK_SECRET=

# Resend
RESEND_API_KEY=

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000

提示词模板 14：GitHub Actions CI/CD 配置

请为以下项目生成 GitHub Actions CI/CD 配置：

技术栈：Next.js 15 + TypeScript + pnpm
部署平台：Vercel
测试框架：Vitest（单元测试）+ Playwright（E2E）

请生成 .github/workflows/ci.yml，包含：

1. **触发条件**：
   - push 到 main 分支
   - Pull Request 到 main 分支

2. **CI 流程**：
   - 安装依赖（pnpm，带缓存）
   - 类型检查（tsc --noEmit）
   - Lint 检查（eslint 或 biome）
   - 单元测试（vitest run）
   - 构建检查（next build）

3. **部署流程**（仅 main 分支 push）：
   - Vercel 自动部署（通过 Vercel GitHub 集成）
   - 或手动触发 Vercel CLI 部署

4. **优化**：
   - pnpm store 缓存
   - Next.js 构建缓存
   - 并行执行独立步骤

注意：Vercel 通常自带 Git 集成自动部署，
GitHub Actions 主要用于 CI 检查（类型/lint/测试）。

# .github/workflows/ci.yml
name: CI
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'pnpm'
      
      - run: pnpm install --frozen-lockfile
      
      - name: Type Check
        run: pnpm tsc --noEmit
      
      - name: Lint
        run: pnpm lint
      
      - name: Unit Tests
        run: pnpm test -- --run
      
      - name: Build
        run: pnpm build

Vercel 部署配置清单：

□ 在 Vercel 中导入 GitHub 仓库
□ 配置环境变量（从 .env.local 复制到 Vercel Dashboard）
□ 确认构建设置：
  ├── Framework Preset: Next.js
  ├── Build Command: pnpm build（或默认）
  ├── Output Directory: .next（默认）
  └── Install Command: pnpm install
□ 配置自定义域名（可选）
□ 启用 Preview Deployments（PR 自动预览）
□ 测试部署：push 一次代码，确认自动部署成功

提示词模板 15：Steering 规则文件完善

基于以下实际项目结构和技术栈，完善 Kiro Steering 规则文件：

项目结构：[粘贴实际目录结构]
技术栈：Next.js 15 App Router + TypeScript + Tailwind CSS + shadcn/ui + Supabase
设计系统：[粘贴设计系统文档摘要]

请生成 .kiro/steering/coding-standards.md，包含：

## 技术栈约束
- 框架：Next.js 15 App Router（不使用 Pages Router）
- 语言：TypeScript strict 模式
- 样式：Tailwind CSS + shadcn/ui（不使用 CSS Modules 或 styled-components）
- 数据获取：优先使用 Server Components + Server Actions
- 状态管理：React 内置状态（useState/useReducer），不使用 Redux/Zustand
- 表单：react-hook-form + zod 验证

## 文件组织规则
- 按功能模块组织代码（features/ 目录）
- 每个功能模块包含：components/, actions.ts, hooks.ts, types.ts
- 共享 UI 组件放在 components/ui/（shadcn/ui）
- 共享业务组件放在 components/shared/
- 工具函数放在 lib/

## 命名规范
- 文件名：kebab-case（如 user-profile.tsx）
- 组件名：PascalCase（如 UserProfile）
- 函数名：camelCase（如 getUserProfile）
- 常量名：UPPER_SNAKE_CASE（如 MAX_FILE_SIZE）
- 类型名：PascalCase（如 UserProfile）
- CSS 变量：kebab-case（如 --primary-foreground）

## 组件规则
- 优先使用 Server Components（默认）
- 仅在需要交互时使用 Client Components（'use client'）
- Client Components 尽量小，只包装交互部分
- 使用 shadcn/ui 组件，不自己造轮子
- 每个组件文件只导出一个组件

## 数据获取规则
- 服务端数据获取使用 Server Components 直接查询
- 表单提交使用 Server Actions
- 仅在需要实时更新时使用客户端数据获取
- Supabase 查询使用 server.ts 中的客户端（服务端）
- 浏览器端 Supabase 操作使用 client.ts 中的客户端

## 错误处理规则
- Server Actions 返回 { success: boolean, data?, error? } 格式
- 使用 Error Boundary 捕获渲染错误
- 使用 Toast 通知用户操作结果
- API 错误返回标准格式 { error: string, code: number }
- 不在客户端暴露敏感错误信息

## 安全规则
- 所有环境变量通过 process.env 访问，不硬编码
- 公开变量使用 NEXT_PUBLIC_ 前缀
- 服务端密钥绝不暴露到客户端
- 所有用户输入使用 zod 验证
- Supabase RLS 策略保护数据访问
- API Routes 验证认证状态

## 测试规则
- 核心业务逻辑使用 Vitest 单元测试
- 关键用户流程使用 Playwright E2E 测试
- 测试文件与源文件同目录，命名为 *.test.ts
- 不 mock 数据库，使用测试数据库

## 禁止事项
- 禁止使用 any 类型（使用 unknown 或具体类型）
- 禁止使用 var（使用 const/let）
- 禁止在 Server Components 中使用 useEffect/useState
- 禁止直接操作 DOM（使用 React 方式）
- 禁止在客户端暴露 SUPABASE_SERVICE_ROLE_KEY
- 禁止跳过 TypeScript 类型检查（@ts-ignore）

提示词模板 16：MCP 配置生成

基于以下项目需求，生成 Kiro MCP 配置：

项目技术栈：[技术栈]
需要连接的服务：
- 数据库：Supabase PostgreSQL
- 文件系统：项目文件读写
- API 文档：[外部 API 文档 URL]

请生成 .kiro/mcp.json 配置文件，包含：

1. **文件系统 MCP**：读取项目文件（用于上下文）
2. **数据库 MCP**（如适用）：查询 Supabase schema
3. **浏览器 MCP**（如适用）：访问 API 文档

每个 MCP Server 配置包含：
- server 名称
- 命令和参数
- 环境变量（如需要）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "./src",
        "./docs"
      ]
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "DATABASE_URL": "postgresql://..."
      }
    }
  }
}

MCP 配置决策树：

你的项目需要 MCP 吗？
│
├── 需要查询数据库 schema？
│   └── 是 → 配置 PostgreSQL MCP
│
├── 需要读取外部 API 文档？
│   └── 是 → 配置 Fetch/Browser MCP
│
├── 需要搜索代码仓库？
│   └── 是 → Kiro 内置文件搜索已足够
│
└── MVP 阶段通常不需要复杂的 MCP 配置
    └── 先用 Kiro 内置功能，遇到瓶颈再添加

核心模块开发优先级：

1. 认证模块（Day 4 上午）
   ├── Supabase Auth 集成
   ├── 登录/注册页面连接
   ├── 中间件保护路由
   └── 用户会话管理

2. 数据库 Schema（Day 4 下午）
   ├── Supabase 中创建表
   ├── RLS 策略配置
   ├── TypeScript 类型生成
   └── 基础 CRUD 操作

3. 布局和导航（Day 4 下午）
   ├── 根布局（Header + Footer）
   ├── Dashboard 布局（Sidebar + Main）
   ├── 响应式导航
   └── 主题切换

4. 核心功能模块 v1（Day 5）
   ├── 选择最核心的 1 个功能模块
   ├── 实现基础 CRUD
   ├── 连接 UI 和数据
   └── 基本的错误处理

注意：使用 Kiro Spec-Driven 工作流执行任务！

Kiro Spec-Driven 开发流程（每个任务）：

1. 打开 tasks.md，找到当前要执行的任务
2. 告诉 Kiro："执行任务 X.Y"
3. Kiro 读取 Spec 上下文（requirements + design + tasks）
4. Kiro 生成代码
5. 你审查代码：
   ├── 代码逻辑是否正确？
   ├── 是否遵循 Steering 规则？
   ├── 是否有安全问题？
   ├── 是否有遗漏的错误处理？
   └── 类型定义是否完整？
6. 运行测试验证
7. 标记任务完成
8. 进入下一个任务

每个任务预计 15-30 分钟（含审查时间）
Day 4-5 预计完成 8-12 个任务

提示词模板 17：认证模块实现指导

请实现 Supabase Auth 认证模块，要求如下：

技术栈：Next.js 15 App Router + Supabase Auth + TypeScript
Steering 规则：[参考 .kiro/steering/coding-standards.md]

需要实现：

1. **Supabase 客户端配置**：
   - lib/supabase/client.ts（浏览器端）
   - lib/supabase/server.ts（服务端）
   - lib/supabase/middleware.ts（中间件）

2. **认证中间件**：
   - middleware.ts（根目录）
   - 保护 /dashboard/* 路由
   - 未登录用户重定向到 /login
   - 已登录用户访问 /login 重定向到 /dashboard

3. **登录页面**：
   - app/(auth)/login/page.tsx
   - 邮箱+密码登录
   - OAuth 登录（GitHub）
   - 错误处理和加载状态

4. **注册页面**：
   - app/(auth)/register/page.tsx
   - 邮箱+密码注册
   - 表单验证（zod）
   - 注册成功后发送验证邮件

5. **Server Actions**：
   - features/auth/actions.ts
   - signIn, signUp, signOut, resetPassword

请遵循 Steering 规则中的错误处理格式和命名规范。

提示词模板 18：数据库 Schema 实现指导

请在 Supabase 中创建以下数据库 Schema：

数据模型：[粘贴 design.md 中的数据模型]

需要实现：

1. **SQL 迁移文件**：
   - CREATE TABLE 语句
   - 索引定义
   - 外键约束

2. **RLS 策略**：
   - 每个表的行级安全策略
   - 用户只能访问自己的数据
   - 管理员可以访问所有数据（如适用）

3. **TypeScript 类型**：
   - 使用 Supabase CLI 生成类型
   - 或手动定义与 Schema 对应的 TypeScript 接口

4. **基础查询函数**：
   - features/[module]/actions.ts 中的 CRUD 操作
   - 使用 Server Actions 格式
   - 包含错误处理

命令参考：
```bash
# 生成 TypeScript 类型
npx supabase gen types typescript --project-id your-project-id > src/types/database.ts

### 3.8 Day 3-5 每日检查清单

#### Day 3 检查清单

#### Day 4 检查清单

#### Day 5 检查清单

---

## 实战案例：5 天完成"AI 代码审查工具"的设计与开发启动

### 案例背景

延续第 1 周的案例——一位全栈开发者正在构建 CodeLens，一个面向中小团队的 AI 代码审查工具。第 1 周已完成调研、需求定义和架构设计，现在进入第 2 周。

### Day 1：UI/UX 设计

### Day 2：设计审查与设计系统

### Day 3：项目初始化与 CI/CD

### Day 4-5：核心模块开发

### 案例总结

---

## 避坑指南

### ❌ 常见错误

1. **在设计上花太多时间**
   - 问题：花 3 天打磨 Landing Page 的每一个像素，核心功能还没开始
   - 正确做法：Day 1 用 v0.dev 快速生成"够用"的设计，上线后再迭代。80% 的设计质量只需要 20% 的时间
   - 检验标准：Day 1 结束时所有页面都有设计稿，即使不完美

2. **跳过设计系统直接开发**
   - 问题：每个页面的颜色、间距、组件样式都不一样，后期统一成本极高
   - 正确做法：Day 2 花半天建立 CSS 变量和组件规范，这是"磨刀不误砍柴工"
   - 检验标准：所有颜色和间距都通过 CSS 变量引用，没有硬编码的颜色值

3. **忽视全状态设计**
   - 问题：只设计了"有数据"的正常状态，上线后用户看到空白页面、无限 loading、神秘报错
   - 正确做法：每个页面必须覆盖空状态、加载状态、错误状态、成功状态
   - 检验标准：用"新用户首次登录"的视角走一遍所有页面

4. **CI/CD 配置拖到最后**
   - 问题：开发了 3 周才配置 CI/CD，发现一堆类型错误和 lint 问题需要修复
   - 正确做法：Day 3 就配置好 CI/CD，每次 push 都自动检查，问题早发现早修复
   - 检验标准：第一次 push 就触发 CI 检查并通过

5. **不配置 Steering 文件就开始编码**
   - 问题：AI 生成的代码风格不一致——有的用 CSS Modules，有的用 Tailwind；有的用 Pages Router，有的用 App Router
   - 正确做法：在写第一行业务代码之前，先配置好 Steering 规则
   - 检验标准：Steering 文件至少包含技术栈约束、命名规范、组件规则、安全规则

6. **试图在 Day 3-5 完成所有功能**
   - 问题：急于求成，代码质量差，bug 多，后面花更多时间修复
   - 正确做法：Day 3-5 只完成项目骨架 + 1-2 个核心模块的基础实现，核心开发在 Week 3-4 系统化推进
   - 检验标准：Day 5 结束时有一个可登录、可演示核心功能的应用，而不是一个半成品

7. **手动部署而不是自动化**
   - 问题：每次部署都要手动执行 10 个步骤，容易出错，浪费时间
   - 正确做法：Vercel + GitHub 集成，push 到 main 自动部署，PR 自动生成 Preview
   - 检验标准：从 push 代码到线上更新，零手动操作

8. **设计和开发完全脱节**
   - 问题：v0.dev 生成的设计代码和实际项目代码是两套，需要手动"翻译"
   - 正确做法：v0.dev 生成的代码直接基于 shadcn/ui + Tailwind，可以直接复制到项目中使用
   - 检验标准：v0.dev 生成的组件代码复制到项目后，只需要少量修改就能运行

### ✅ 最佳实践

1. **设计→系统→代码的顺序不能乱**：先有设计稿，再建设计系统，最后写代码。跳过任何一步都会在后面付出代价
2. **v0.dev 是原型工具，不是最终产品**：用它快速生成 80% 的 UI，剩下 20% 在开发中迭代
3. **CSS 变量是设计系统的核心**：所有视觉属性（颜色、间距、圆角、阴影）都通过 CSS 变量管理
4. **shadcn/ui 是 Solo Founder 的最佳选择**：代码在你的项目中，完全可控，AI 生成质量高
5. **CI/CD 从 Day 1 就配置**：自动化检查是代码质量的第一道防线
6. **Steering 文件是 AI 编码的"说明书"**：投入 30 分钟配置，节省后续数小时的代码修复
7. **每天结束时确保代码可部署**：不要积累"技术债"到周末才处理
8. **用 Spec-Driven 工作流而不是随意编码**：每个任务都有明确的输入（Spec）和输出（代码），可追踪、可审查

---

## 第 2 周每日检查清单

### Day 1 检查清单（UI/UX 设计）

### Day 2 检查清单（设计审查与设计系统）

### Day 3 检查清单（项目初始化与 CI/CD）

### Day 4 检查清单（认证与数据库）

### Day 5 检查清单（核心模块 v1）

---

## 相关资源与延伸阅读

### AI 设计工具

| 资源 | 类型 | 链接 | 说明 |
|------|------|------|------|
| v0.dev | AI UI 生成 | [v0.dev](https://v0.dev) | Vercel 的 AI UI 生成工具，直接输出 React + shadcn/ui 代码 |
| Google Stitch | AI UI 设计 | [stitch.withgoogle.com](https://stitch.withgoogle.com) | 原 Galileo AI，被 Google 收购后重新发布 |
| Figma AI | 设计辅助 | [figma.com](https://www.figma.com) | Figma 内置 AI 功能，辅助设计生成和修改 |
| Realtime Colors | 配色预览 | [realtimecolors.com](https://realtimecolors.com) | 在真实 UI 中实时预览配色方案 |
| Coolors | 配色生成 | [coolors.co](https://coolors.co) | AI 驱动的配色方案生成器 |

### 设计系统与组件库

| 资源 | 类型 | 链接 | 说明 |
|------|------|------|------|
| shadcn/ui | 组件库 | [ui.shadcn.com](https://ui.shadcn.com) | 2026 年最流行的 React 组件集合，代码复制模式 |
| Radix UI | 无障碍原语 | [radix-ui.com](https://www.radix-ui.com) | shadcn/ui 的底层，提供无障碍交互原语 |
| Tailwind CSS | 样式框架 | [tailwindcss.com](https://tailwindcss.com) | 实用优先的 CSS 框架 |
| CSS Variables Guide | 教程 | [frontendtools.tech](https://www.frontendtools.tech/blog/css-variables-guide-design-tokens-theming-2025) | CSS 变量与设计 Token 的完整指南 |

### 开发工具与平台

| 资源 | 类型 | 链接 | 说明 |
|------|------|------|------|
| Kiro | AI IDE | [kiro.dev](https://kiro.dev) | Spec-Driven 开发的 AI IDE |
| Vercel | 部署平台 | [vercel.com](https://vercel.com) | Next.js 零配置部署 |
| Supabase | 后端即服务 | [supabase.com](https://supabase.com) | 开源 Firebase 替代，内置 Auth + DB + Storage |
| GitHub Actions | CI/CD | [github.com/features/actions](https://github.com/features/actions) | 自动化构建、测试和部署 |

### 设计最佳实践

| 资源 | 类型 | 链接 | 说明 |
|------|------|------|------|
| Mobbin | 设计参考 | [mobbin.com](https://mobbin.com) | 优秀 App 的 UI 设计参考库 |
| Refactoring UI | 书籍 | [refactoringui.com](https://www.refactoringui.com) | 开发者学设计的经典书籍 |
| Laws of UX | 设计原则 | [lawsofux.com](https://lawsofux.com) | UX 设计的核心法则 |
| Checklist Design | 清单 | [checklist.design](https://www.checklist.design) | UI 组件设计检查清单 |

---

## 参考来源

- [Skywork AI - Vercel v0 Review 2025: AI-Powered UI Code Generation](https://skywork.ai/blog/vercel-v0-review-2025-ai-ui-code-generation-nextjs/)（2025-09）
- [AI Chief - v0 dev Review: Cost, Use Cases & Alternatives 2026](https://www.aichief.com/ai-development-tools/v0-dev/)（2025-09）
- [Gapsy Studio - From Galileo AI to Google Stitch: Your Guide to AI Design](https://gapsystudio.com/blog/galileo-ai-design/)（2025-12）
- [Design Revision - shadcn UI: Complete Guide to the Most Popular React Component Collection 2026](https://designrevision.com/blog/shadcn-ui-guide)（2026-02）
- [Frontend Tools - CSS Variables Guide: Design Tokens & Theming 2025](https://www.frontendtools.tech/blog/css-variables-guide-design-tokens-theming-2025)（2026-01）
- [Kiro Documentation - Your First Project](https://kiro.dev/docs/getting-started/first-project)（2025-07）
- [Kiro Documentation - Extending Kiro with MCP](https://kiro.dev/docs/guides/learn-by-playing/07-extending-kiro-with-mcp/)（2025-07）
- [Brian Beach - Teaching Kiro New Tricks with Agent Steering and MCP](https://blog.brianbeach.com/publications/2025-10-23-teaching-kiro-new-tricks/)（2025-10）
- [Vercel - How to Use GitHub Actions with Vercel](https://vercel.com/guides/how-can-i-use-github-actions-with-vercel)（2025-11）
- [AI Founder Kit - Galileo AI Review 2025: Instant UI Design Generation](https://aifounderkit.com/ai-tools/galileo-ai-review-features-pricing-alternatives/)（2025-06）

Content was rephrased for compliance with licensing restrictions.

---

> 📖 返回 [总览与导航](../00-总览与导航.md) | 上一节：[第1周：调研·需求·架构](36b-第1周-调研需求架构.md) | 下一节：[第3-4周：Spec-Driven开发](36d-第3-4周-Spec-Driven开发.md)