36d - 第3-4周：Spec-Driven 开发

Spec-Driven 开发的核心公式：

  Spec + AI Agent + Human Review = 生产级代码

其中：
├── Spec = requirements.md + design.md + tasks.md
├── AI Agent = Kiro / Cursor / Claude Code
├── Human Review = 你的审查、测试、决策
└── 生产级代码 = 可部署、可维护、有测试覆盖的代码

.kiro/specs/[feature-name]/
├── requirements.md    ← 定义"做什么"（What）
├── design.md          ← 定义"怎么做"（How）
└── tasks.md           ← 定义"执行步骤"（Steps）

requirements.md 结构：

  用户故事
  As a [角色], I want [功能], so that [价值]

  验收标准
  1. WHEN [条件], THE system SHALL [行为]
  2. WHEN [条件], THE system SHALL [行为]

  非功能需求
  - 性能：页面加载 < 2 秒
  - 安全：所有输入必须验证
  - 可用性：支持移动端

design.md 结构：

  架构概览
  - 技术选型和理由
  - 组件关系图

  数据模型
  - 数据库 Schema
  - 类型定义

  API 设计
  - 端点定义
  - 请求/响应格式

  错误处理策略
  - 错误分类
  - 用户反馈方式

tasks.md 结构：

  - [ ] 1. 功能模块 A
    - [ ] 1.1 实现数据模型
    - [ ] 1.2 实现 Server Actions
    - [ ] 1.3 实现 UI 组件
    - [ ] 1.4 编写测试
  - [ ] 2. 功能模块 B
    - [ ] 2.1 ...

每天开始前，打开 tasks.md：

1. 找到第一个未完成的任务（标记为 [ ]）
2. 阅读任务描述和关联的需求编号
3. 回到 requirements.md 查看对应的验收标准
4. 回到 design.md 查看对应的技术设计
5. 确认你理解了这个任务要做什么

⚠️ 关键原则：一次只关注一个任务！
不要试图一次实现整个功能模块。

单任务执行流程：

1. 告诉 AI："执行任务 X.Y"
   └── AI 读取 Spec 上下文（requirements + design + tasks）

2. AI 生成代码
   └── 可能涉及多个文件的创建或修改

3. 你审查代码（详见第 3 节）
   ├── 逻辑正确性
   ├── 是否遵循 Steering 规则
   ├── 安全性检查
   ├── 错误处理完整性
   └── 类型定义完整性

4. 运行测试验证
   ├── 单元测试通过
   ├── 类型检查通过
   └── 构建成功

5. 标记任务完成
   └── tasks.md 中 [ ] → [x]

6. Git 提交
   └── 一个任务一个 commit

7. 进入下一个任务

任务依赖处理策略：

tasks.md 中的任务通常按依赖顺序排列：
├── 数据模型 → Server Actions → UI 组件 → 测试
├── 核心功能 → 辅助功能 → 集成功能
└── 后端逻辑 → 前端展示 → 交互优化

如果发现当前任务依赖未完成的前置任务：
├── 检查是否遗漏了前置任务
├── 如果是，先完成前置任务
└── 如果前置任务在另一个 Spec 中，先完成那个 Spec

请执行 tasks.md 中的任务 [X.Y]。

在开始之前，请先：
1. 阅读 requirements.md 中对应的验收标准
2. 阅读 design.md 中对应的技术设计
3. 检查已完成的相关任务，了解现有代码上下文

然后：
- 只实现这一个任务的功能，不要超出范围
- 遵循 .kiro/steering/ 中的编码规范
- 包含必要的错误处理
- 添加 TypeScript 类型定义
- 如果任务涉及 UI，覆盖空/加载/错误/成功状态

任务 [X.Y] 看起来比较复杂。请帮我把它拆分成更小的子步骤：

任务描述：[粘贴任务描述]
相关需求：[粘贴验收标准]
相关设计：[粘贴技术设计]

请拆分为 3-5 个可独立完成和验证的子步骤，每个步骤：
1. 有明确的输入和输出
2. 可以独立测试
3. 预计 10-15 分钟完成

在执行任务 [X.Y] 时，我发现以下问题：

[描述发现的问题或需求变更]

请帮我：
1. 评估这个变更对现有 Spec 的影响
2. 建议如何更新 requirements.md
3. 建议如何更新 design.md
4. 建议如何更新 tasks.md（是否需要新增/修改/删除任务）
5. 评估对已完成任务的影响（是否需要回退修改）

两周开发节奏总览：

Week 3（核心功能开发）：
├── Day 1-2：核心功能模块 A（数据模型 + 业务逻辑 + UI）
├── Day 3-4：核心功能模块 B（数据模型 + 业务逻辑 + UI）
└── Day 5：核心功能模块 C + 集成测试

Week 4（功能完善 + 集成）：
├── Day 1-2：辅助功能（设置、通知、导出等）
├── Day 3：支付集成（Stripe / Lemon Squeezy）
├── Day 4：第三方服务集成（邮件、OAuth 等）
└── Day 5：全功能集成测试 + Bug 修复

预期产出：
├── 核心功能 100% 完成
├── 辅助功能 80% 完成
├── 测试覆盖率 > 60%
├── 所有 Spec 任务标记完成
└── 可演示的完整 MVP

┌─────────────────────────────────────────────────────────────────┐
│                    每日开发时间表（8 小时）                        │
├──────────────┬──────────────────────────────────────────────────┤
│ 09:00-09:15  │ 🎯 晨间规划                                      │
│              │ ├── 查看昨天的进度（tasks.md 完成情况）             │
│              │ ├── 确定今天要完成的 2-4 个任务                    │
│              │ ├── 检查是否有阻塞项需要先解决                     │
│              │ └── 打开相关的 Spec 文件和代码文件                  │
├──────────────┼──────────────────────────────────────────────────┤
│ 09:15-11:30  │ 💻 深度编码 Session 1（2.25 小时）                │
│              │ ├── 执行 2 个 Spec 任务                           │
│              │ ├── 每个任务：AI 生成 → 审查 → 测试 → 提交         │
│              │ └── 这是一天中认知能力最强的时段                    │
├──────────────┼──────────────────────────────────────────────────┤
│ 11:30-12:00  │ 👀 代码审查 + 测试                                │
│              │ ├── 审查上午完成的代码                              │
│              │ ├── 运行测试套件                                   │
│              │ ├── 修复发现的问题                                  │
│              │ └── Git commit + push                              │
├──────────────┼──────────────────────────────────────────────────┤
│ 12:00-13:00  │ 🍽️ 午休（完全离开电脑）                           │
├──────────────┼──────────────────────────────────────────────────┤
│ 13:00-15:30  │ 💻 深度编码 Session 2（2.5 小时）                 │
│              │ ├── 执行 2 个 Spec 任务                           │
│              │ ├── 下午适合处理相对简单的任务                      │
│              │ └── 或处理上午遗留的复杂问题                        │
├──────────────┼──────────────────────────────────────────────────┤
│ 15:30-16:00  │ ☕ 短休息 + 回顾                                  │
├──────────────┼──────────────────────────────────────────────────┤
│ 16:00-16:30  │ 👀 代码审查 + 测试                                │
│              │ ├── 审查下午完成的代码                              │
│              │ ├── 运行完整测试套件                                │
│              │ ├── 修复失败的测试                                  │
│              │ └── Git commit + push                              │
├──────────────┼──────────────────────────────────────────────────┤
│ 16:30-17:00  │ 📝 收尾 + 规划                                    │
│              │ ├── 更新 tasks.md 状态                             │
│              │ ├── 记录遇到的问题和解决方案                        │
│              │ ├── 规划明天的任务                                  │
│              │ └── 推送所有代码到远程仓库                          │
└──────────────┴──────────────────────────────────────────────────┘

7 条黄金法则：

1. 一次一个任务
   ├── 不要让 AI 一次实现整个功能模块
   ├── 每个任务完成后必须测试验证
   └── 小步前进，每步都确认正确

2. 先核心逻辑，再 UI
   ├── 数据模型 → 业务逻辑 → API → UI
   ├── 核心逻辑是最难的部分，也是最容易出错的
   └── UI 可以后续快速迭代，逻辑错误修复成本高

3. 每个任务一个 commit
   ├── 小步提交，保持 Git 历史清晰
   ├── commit message 要有意义（见 Git 工作流章节）
   └── 方便回退：如果某个任务引入 bug，可以精确回退

4. 先写测试，再标记完成
   ├── 至少为核心逻辑写单元测试
   ├── 测试通过才能标记任务完成
   └── 测试是你对代码正确性的信心来源

5. 遇到困难不要死磕
   ├── 超过 30 分钟没进展 → 换个思路
   ├── 让 AI 提供 2-3 种替代方案
   ├── 选择最简单的方案先实现
   └── 记录问题，后续优化

6. 保持 Spec 同步
   ├── 发现需求变更 → 先更新 Spec，再改代码
   ├── 发现设计缺陷 → 先更新 design.md，再实现
   └── Spec 是"单一事实来源"，代码跟随 Spec

7. 每天部署预览
   ├── 每天至少 push 一次到远程仓库
   ├── Vercel Preview 自动部署
   ├── 在真实环境中验证功能
   └── 尽早发现环境相关的问题

任务复杂度与时间预估：

简单任务（15-20 分钟）：
├── 创建数据模型 / TypeScript 类型
├── 实现简单的 CRUD Server Action
├── 创建静态 UI 组件
├── 配置环境变量或第三方服务
└── 编写简单的单元测试

中等任务（30-45 分钟）：
├── 实现带验证的表单组件
├── 实现带分页/筛选的列表页面
├── 集成第三方 API（Stripe、OAuth）
├── 实现复杂的业务逻辑
└── 编写集成测试

复杂任务（60-90 分钟）：
├── 实现实时功能（WebSocket / SSE）
├── 实现文件上传/处理流水线
├── 实现复杂的状态机逻辑
├── 性能优化（缓存、懒加载）
└── 安全相关功能（权限、加密）

每天的理想组合：
├── 上午：1 个中等 + 1 个简单（或 1 个复杂）
└── 下午：1 个中等 + 1 个简单（或 1 个复杂）

进度落后的信号：
├── 连续 2 天完成的任务少于 2 个
├── 某个任务卡了超过 2 小时
├── 测试持续失败无法修复
└── 发现需要大量返工

应对策略：

1. 简化当前任务
   ├── 把复杂任务拆成更小的子任务
   ├── 先实现最小可用版本，标记 TODO 后续优化
   └── 降低完美度要求，"能用"优先于"完美"

2. 调整 Spec 范围
   ├── 重新评估 MVP 范围
   ├── 把非核心功能移到"Phase 2"
   ├── 更新 tasks.md，标记延后的任务
   └── 保持核心功能的完整性

3. 换工具或方法
   ├── Kiro 生成效果不好 → 试试 Cursor 或 Claude Code
   ├── 从零实现太慢 → 找开源库或模板
   ├── 自己写太慢 → 让 AI 生成更多，你只审查
   └── 某个技术方案不行 → 换更简单的方案

4. 寻求外部帮助
   ├── Stack Overflow / GitHub Issues
   ├── AI 对话（Claude / GPT）深入讨论技术问题
   ├── 相关社区（Discord / Reddit）
   └── 付费咨询（Toptal / Codementor）作为最后手段

今天是 [项目名] 开发的第 [N] 天（Week [3/4]）。

昨天完成的任务：
- [x] [任务编号] [任务描述]
- [x] [任务编号] [任务描述]

昨天遇到的问题：
- [问题描述]

当前 tasks.md 状态：
- 总任务数：[N]
- 已完成：[N]
- 剩余：[N]
- 剩余工作日：[N]

请帮我：
1. 评估当前进度是否正常（按每天 2-4 个任务的节奏）
2. 建议今天应该优先完成的 2-4 个任务
3. 如果进度落后，建议哪些任务可以简化或延后
4. 提醒我今天需要注意的技术风险

AI 生成代码的常见问题模式：

1. 逻辑错误
   ├── 边界条件处理不完整（空数组、null 值、零值）
   ├── 循环的 off-by-one 错误
   ├── 异步操作的竞态条件
   └── 条件判断的逻辑漏洞

2. 安全漏洞
   ├── 缺少输入验证
   ├── SQL 注入风险（拼接查询）
   ├── XSS 风险（未转义用户输入）
   ├── 敏感信息泄露（错误消息中暴露内部细节）
   └── 权限检查遗漏

3. 性能问题
   ├── N+1 查询（循环中查询数据库）
   ├── 不必要的重渲染（React 组件）
   ├── 大数据集未分页
   ├── 缺少缓存策略
   └── 同步阻塞操作

4. 可维护性问题
   ├── 过度抽象（不需要的设计模式）
   ├── 魔法数字和硬编码字符串
   ├── 缺少类型定义（使用 any）
   ├── 命名不一致
   └── 重复代码（未提取公共函数）

5. 幻觉问题
   ├── 使用不存在的 API 或方法
   ├── 引用错误的库版本
   ├── 编造的配置选项
   └── 不正确的类型签名

快速扫描清单：

□ 文件变更范围是否合理？
  ├── 只修改了与当前任务相关的文件？
  ├── 没有意外修改不相关的文件？
  └── 新增文件的位置是否正确？

□ 代码量是否合理？
  ├── 不是过度工程（简单功能写了 500 行）？
  ├── 不是过于简陋（缺少必要的错误处理）？
  └── 与任务复杂度匹配？

□ 是否遵循项目规范？
  ├── 文件命名符合 kebab-case？
  ├── 组件命名符合 PascalCase？
  ├── 使用了 shadcn/ui 组件而非自造轮子？
  └── 使用了 Server Components（默认）？

逻辑审查清单：

□ 核心逻辑是否正确？
  ├── 对照验收标准逐条检查
  ├── 边界条件是否处理（空值、零值、极大值）
  ├── 错误路径是否处理
  └── 异步操作是否正确 await

□ 数据流是否正确？
  ├── 输入验证是否完整（zod schema）
  ├── 数据转换是否正确
  ├── 输出格式是否符合预期
  └── 状态更新是否正确

□ 类型定义是否完整？
  ├── 没有使用 any 类型
  ├── 函数参数和返回值都有类型
  ├── 接口定义与数据库 Schema 一致
  └── 可选字段正确标记（?）

安全审查清单：

□ 输入验证
  ├── 所有用户输入都经过 zod 验证？
  ├── 文件上传有大小和类型限制？
  └── URL 参数有验证？

□ 权限检查
  ├── Server Actions 检查了用户认证状态？
  ├── 数据访问有 RLS 策略保护？
  ├── 敏感操作有权限验证？
  └── 不同角色的权限边界清晰？

□ 数据安全
  ├── 敏感数据没有暴露到客户端？
  ├── 错误消息不包含内部细节？
  ├── 环境变量使用正确（NEXT_PUBLIC_ 前缀）？
  └── 没有硬编码的密钥或密码？

请审查以下代码变更，这是 [任务描述] 的实现：

[粘贴代码或描述文件变更]

审查维度：
1. **正确性**：逻辑是否正确？边界条件是否处理？
2. **安全性**：是否有输入验证？权限检查？数据泄露风险？
3. **性能**：是否有 N+1 查询？不必要的重渲染？大数据集处理？
4. **可维护性**：命名是否清晰？是否有重复代码？抽象层次是否合理？
5. **错误处理**：所有错误路径是否处理？用户反馈是否友好？
6. **类型安全**：TypeScript 类型是否完整？是否有 any？

对应的验收标准：
[粘贴 requirements.md 中的验收标准]

请列出发现的问题，按严重程度排序（Critical > Major > Minor）。

请对以下代码进行安全审查：

[粘贴代码]

重点检查：
1. SQL 注入：是否使用参数化查询？
2. XSS：用户输入是否正确转义？
3. CSRF：表单提交是否有 CSRF 保护？
4. 认证绕过：是否所有受保护路由都检查了认证？
5. 授权漏洞：用户是否只能访问自己的数据？
6. 敏感数据泄露：错误消息是否暴露内部信息？
7. 依赖安全：是否使用了已知有漏洞的依赖？
8. 环境变量：敏感配置是否正确保护？

请为每个发现的问题提供修复建议。

代码审查时间分配（每天约 1 小时）：

上午 Session 结束后（11:30-12:00）：
├── 审查上午 2 个任务的代码（15 分钟）
├── 运行测试套件（5 分钟）
└── 修复发现的问题（10 分钟）

下午 Session 结束后（16:00-16:30）：
├── 审查下午 2 个任务的代码（15 分钟）
├── 运行完整测试套件（5 分钟）
└── 修复发现的问题（10 分钟）

审查深度指南：
├── 核心业务逻辑：深度审查（逐行阅读）
├── UI 组件：中度审查（检查状态覆盖和交互）
├── 配置文件：快速审查（检查关键配置项）
├── 测试代码：中度审查（检查测试覆盖和断言）
└── 类型定义：快速审查（检查完整性和一致性）

测试金字塔（Solo Founder 版）：

        ┌─────────┐
        │  E2E    │  ← 少量（3-5 个关键用户流程）
        │  测试   │     Week 5 集中编写
        ├─────────┤
        │  集成   │  ← 适量（核心 API 和数据流）
        │  测试   │     每个功能模块 2-3 个
        ├─────────┤
        │  单元   │  ← 大量（核心业务逻辑）
        │  测试   │     每个任务完成后编写
        ├─────────┤
        │  PBT    │  ← 关键逻辑（数据转换、计算、验证）
        │  属性测试│     发现边界情况的利器
        └─────────┘
        │  类型   │  ← 全覆盖（TypeScript strict 模式）
        │  检查   │     编译时自动检查
        └─────────┘

Week 3-4 的测试重点：
├── 每个任务完成后：运行类型检查 + 相关单元测试
├── 每天结束时：运行完整测试套件
├── 核心逻辑：编写单元测试 + PBT
└── E2E 测试留到 Week 5

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import path from 'path'
 
export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./src/test/setup.ts'],
    include: ['src/**/*.test.{ts,tsx}'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'html'],
      include: ['src/features/**/*.ts', 'src/lib/**/*.ts'],
      exclude: ['**/*.test.ts', '**/*.d.ts'],
    },
  },
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

// package.json 中添加测试脚本
{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "test:coverage": "vitest run --coverage",
    "test:ui": "vitest --ui",
    "test:e2e": "playwright test"
  }
}

测试编写策略：

对于 Server Actions / 业务逻辑：
├── 测试正常路径（happy path）
├── 测试错误路径（invalid input, not found, unauthorized）
├── 测试边界条件（空值、极值）
└── 使用 PBT 测试数据转换逻辑

对于 UI 组件：
├── 测试渲染是否正确
├── 测试用户交互（点击、输入、提交）
├── 测试不同状态（空/加载/错误/成功）
└── 不测试样式（样式变化频繁，测试维护成本高）

对于 API 端点：
├── 测试请求验证
├── 测试响应格式
├── 测试认证和授权
└── 测试错误响应

测试运行时机：

每个任务完成后（即时反馈）：
$ pnpm test:run -- --reporter=verbose

每天结束时（全面检查）：
$ pnpm test:run
$ pnpm tsc --noEmit

推送代码前（最终验证）：
$ pnpm test:run && pnpm tsc --noEmit && pnpm build

CI/CD 中（自动化）：
GitHub Actions 自动运行所有检查

// 示例：用 fast-check 测试价格计算逻辑
import { describe, it, expect } from 'vitest'
import * as fc from 'fast-check'
import { calculateDiscount } from './pricing'
 
describe('calculateDiscount', () => {
  // 属性 1：折扣后价格不应超过原价
  it('折扣后价格 <= 原价', () => {
    fc.assert(
      fc.property(
        fc.float({ min: 0.01, max: 10000, noNaN: true }),  // 原价
        fc.float({ min: 0, max: 100, noNaN: true }),        // 折扣百分比
        (price, discountPercent) => {
          const result = calculateDiscount(price, discountPercent)
          return result <= price
        }
      )
    )
  })
 
  // 属性 2：折扣后价格不应为负数
  it('折扣后价格 >= 0', () => {
    fc.assert(
      fc.property(
        fc.float({ min: 0.01, max: 10000, noNaN: true }),
        fc.float({ min: 0, max: 100, noNaN: true }),
        (price, discountPercent) => {
          const result = calculateDiscount(price, discountPercent)
          return result >= 0
        }
      )
    )
  })
 
  // 属性 3：0% 折扣 = 原价
  it('0% 折扣返回原价', () => {
    fc.assert(
      fc.property(
        fc.float({ min: 0.01, max: 10000, noNaN: true }),
        (price) => {
          const result = calculateDiscount(price, 0)
          return Math.abs(result - price) < 0.01
        }
      )
    )
  })
})

PBT 适用场景（Week 3-4 重点）：

✅ 适合 PBT 的逻辑：
├── 价格计算（折扣、税费、汇率）
├── 数据格式转换（日期、货币、单位）
├── 搜索和筛选逻辑
├── 排序算法
├── 输入验证规则
├── 分页逻辑
└── 权限计算

❌ 不适合 PBT 的逻辑：
├── UI 渲染
├── 第三方 API 调用
├── 数据库操作
├── 文件 I/O
└── 配置加载

请为以下函数生成单元测试：

[粘贴函数代码]

测试框架：Vitest
要求：
1. 测试正常路径（至少 2 个用例）
2. 测试错误路径（至少 2 个用例）
3. 测试边界条件（空值、零值、极大值）
4. 使用 describe/it 组织测试
5. 每个测试有清晰的描述
6. 不使用 mock（除非绝对必要）

对应的验收标准：
[粘贴相关验收标准]

请为以下函数生成属性基测试（PBT）：

[粘贴函数代码]

测试框架：Vitest + fast-check
要求：
1. 识别函数的核心属性（不变量）
2. 为每个属性编写 fc.property 测试
3. 设计合理的输入生成器（约束到有效输入空间）
4. 每个属性测试有清晰的描述
5. 至少 3 个属性

属性示例：
- 幂等性：f(f(x)) === f(x)
- 单调性：x > y → f(x) >= f(y)
- 保持不变量：转换前后某个属性不变
- 往返一致性：decode(encode(x)) === x
- 边界保持：输出在预期范围内

Solo Developer Git 策略：

分支模型（极简版）：
├── main          ← 生产分支，始终可部署
├── develop       ← 开发分支，日常开发在这里（可选）
└── feat/xxx      ← 功能分支，大功能时使用（可选）

推荐工作流：
├── 简单功能：直接在 main 上开发 + commit
├── 中等功能：创建 feat/ 分支 → 完成后合并到 main
├── 大功能：创建 feat/ 分支 → 多次 commit → PR 合并
└── 紧急修复：直接在 main 上修复 + commit

⚠️ 关键原则：
├── main 分支始终可部署（CI 通过才能 push）
├── 每个 Spec 任务一个 commit（原子性）
├── commit message 有意义（见下方规范）
└── 每天至少 push 一次到远程仓库

格式：<type>(<scope>): <description>

type 类型：
├── feat:     新功能
├── fix:      Bug 修复
├── refactor: 重构（不改变功能）
├── test:     添加或修改测试
├── docs:     文档变更
├── style:    代码格式（不影响逻辑）
├── chore:    构建/工具/依赖变更
└── perf:     性能优化

scope 范围（可选）：
├── auth:     认证模块
├── dashboard: 仪表板
├── billing:  支付模块
├── api:      API 相关
└── ui:       UI 组件

示例：
├── feat(auth): implement GitHub OAuth login
├── feat(dashboard): add review statistics cards
├── fix(billing): correct discount calculation for annual plans
├── test(auth): add unit tests for sign-up validation
├── refactor(api): extract common error handling middleware
├── chore: update dependencies to latest versions
└── docs: add API documentation for webhook endpoints

每个任务完成后：
$ git add -A
$ git commit -m "feat(module): implement task X.Y description"

每天结束时：
$ git push origin main

创建功能分支（大功能时）：
$ git checkout -b feat/payment-integration
# ... 多次 commit ...
$ git checkout main
$ git merge feat/payment-integration
$ git push origin main
$ git branch -d feat/payment-integration

紧急回退（某个任务引入 bug）：
$ git log --oneline -10          # 查看最近 10 个 commit
$ git revert <commit-hash>       # 回退特定 commit
$ git push origin main

查看进度：
$ git log --oneline --since="1 week ago"  # 本周所有 commit
$ git shortlog -sn --since="1 week ago"   # 本周 commit 统计

理想的 Git 历史（一天的工作）：

$ git log --oneline

a1b2c3d feat(reviews): implement review detail page (task 3.4)
d4e5f6g feat(reviews): add review list with pagination (task 3.3)
h7i8j9k feat(reviews): implement review creation action (task 3.2)
l0m1n2o feat(reviews): create review data model and types (task 3.1)

每个 commit 对应一个 Spec 任务：
├── 可追溯：从 commit 找到对应的任务和需求
├── 可回退：某个任务有问题，精确回退那个 commit
├── 可理解：Git 历史就是开发日志
└── 可审计：任何时候都能看到"为什么做了这个改动"

我刚完成了以下代码变更：

变更的文件：
[列出变更的文件]

变更的内容：
[描述做了什么]

对应的 Spec 任务：
[任务编号和描述]

请生成一个符合 Conventional Commits 规范的 commit message。
格式：<type>(<scope>): <description>

要求：
- description 用英文，简洁明了
- 不超过 72 个字符
- 使用祈使语气（如 "add" 而非 "added"）

阻塞类型与应对策略：

┌─────────────────┬──────────────────────────────────────────────┐
│ 阻塞类型         │ 应对策略                                      │
├─────────────────┼──────────────────────────────────────────────┤
│ 技术难题         │ 30 分钟规则：超时就换方案                       │
│ （不知道怎么实现）│ ├── 让 AI 提供 2-3 种替代方案                  │
│                 │ ├── 选择最简单的方案先实现                      │
│                 │ ├── 搜索 Stack Overflow / GitHub Issues        │
│                 │ └── 标记 TODO，后续优化                         │
├─────────────────┼──────────────────────────────────────────────┤
│ AI 生成质量差    │ 改善上下文                                     │
│ （代码不符合预期）│ ├── 提供更详细的 Spec 描述                     │
│                 │ ├── 在 prompt 中包含相关代码上下文               │
│                 │ ├── 换一个 AI 工具（Kiro → Cursor → Claude）   │
│                 │ └── 手动编写关键部分，让 AI 补充                │
├─────────────────┼──────────────────────────────────────────────┤
│ 第三方服务问题   │ 隔离和模拟                                     │
│ （API 不可用等） │ ├── 用 Mock 数据先完成开发                     │
│                 │ ├── 创建抽象层，后续替换实现                    │
│                 │ ├── 联系服务商支持                              │
│                 │ └── 考虑替代服务                                │
├─────────────────┼──────────────────────────────────────────────┤
│ 需求不明确       │ 回到 Spec                                     │
│ （不确定该做什么）│ ├── 重新阅读 requirements.md                   │
│                 │ ├── 如果 Spec 不够清晰，先更新 Spec             │
│                 │ ├── 做最小实现，标记"待确认"                    │
│                 │ └── 记录问题，后续与用户验证                    │
├─────────────────┼──────────────────────────────────────────────┤
│ 测试持续失败     │ 分析根因                                       │
│                 │ ├── 是测试写错了？还是代码有 bug？              │
│                 │ ├── 用 AI 分析失败原因                          │
│                 │ ├── 简化测试，先验证核心逻辑                    │
│                 │ └── 跳过非关键测试，标记 TODO                   │
├─────────────────┼──────────────────────────────────────────────┤
│ 性能问题         │ 延后优化                                       │
│                 │ ├── Week 3-4 不是优化的时候                     │
│                 │ ├── 记录性能问题，Week 5 集中处理               │
│                 │ ├── 除非严重影响开发体验                        │
│                 │ └── "Make it work, make it right, make it fast"│
└─────────────────┴──────────────────────────────────────────────┘

30 分钟规则：

当你在某个问题上卡了 30 分钟，执行以下流程：

分钟 0-10：自己尝试解决
├── 重新阅读错误信息
├── 检查拼写和语法
├── 查看相关文档
└── 尝试最直觉的修复

分钟 10-20：寻求 AI 帮助
├── 把完整的错误信息和上下文给 AI
├── 让 AI 分析可能的原因
├── 让 AI 提供 2-3 种解决方案
└── 尝试 AI 建议的方案

分钟 20-30：换方案
├── 如果 AI 的方案也不行
├── 考虑完全不同的实现方式
├── 简化需求（先做最小版本）
└── 使用现成的库或模板

超过 30 分钟：做决策
├── 选项 A：用最简单的方案先实现，标记 TODO
├── 选项 B：跳过这个任务，先做其他任务
├── 选项 C：在社区/论坛发帖求助
└── 选项 D：重新评估这个功能是否是 MVP 必需的

需要调整 Spec 的信号：

1. 技术不可行
   ├── 设计中的方案在实现时发现不可行
   ├── 第三方服务不支持预期的功能
   └── 行动：更新 design.md，调整技术方案

2. 范围蔓延
   ├── 实现过程中发现需要更多功能
   ├── "顺便"添加了 Spec 中没有的功能
   └── 行动：评估是否是 MVP 必需，不是则移到 Phase 2

3. 用户反馈
   ├── 早期用户（如果有）提出了新需求
   ├── 发现原始假设有误
   └── 行动：更新 requirements.md，重新评估优先级

4. 时间不够
   ├── 按当前进度无法在 Week 4 结束前完成
   ├── 某些功能比预期复杂得多
   └── 行动：砍掉非核心功能，更新 tasks.md

Spec 调整流程：
├── 1. 识别变更原因
├── 2. 评估影响范围
├── 3. 更新 requirements.md（如果需求变了）
├── 4. 更新 design.md（如果设计变了）
├── 5. 更新 tasks.md（添加/修改/删除任务）
├── 6. 重新评估时间线
└── 7. 继续执行

我在实现 [功能描述] 时遇到了问题。

当前状态：
- 我在做的事情：[描述]
- 期望的结果：[描述]
- 实际的结果：[描述]
- 错误信息：[粘贴完整错误]

已经尝试过的方案：
1. [方案 1 和结果]
2. [方案 2 和结果]

技术栈：[列出相关技术]
相关代码：[粘贴关键代码片段]

请：
1. 分析可能的根本原因
2. 提供 2-3 种不同的解决方案
3. 推荐最简单的方案
4. 如果问题太复杂，建议一个更简单的替代实现

我的 MVP 开发进度如下：

总任务数：[N]
已完成：[N]
剩余工作日：[N]
当前每天完成任务数：[N]

按当前速度，我可能无法在截止日期前完成所有任务。

请帮我：
1. 分析哪些剩余任务是 MVP 绝对必需的
2. 哪些任务可以简化（降低完成标准）
3. 哪些任务可以延后到 Phase 2
4. 建议一个调整后的任务优先级列表
5. 预估调整后能否按时完成

MVP 的核心价值主张：[一句话描述]
目标用户最需要的功能：[列出 top 3]

进度追踪的三个层次：

1. 任务级追踪（每天）
   ├── tasks.md 中的完成状态
   ├── 今天完成了几个任务？
   ├── 与计划相比是超前还是落后？
   └── 工具：tasks.md 本身就是最好的追踪工具

2. 功能级追踪（每 2-3 天）
   ├── 哪些功能模块已完成？
   ├── 哪些功能模块正在进行？
   ├── 哪些功能模块还没开始？
   └── 工具：简单的 Markdown 表格或 Notion 看板

3. 项目级追踪（每周）
   ├── 整体进度百分比
   ├── 是否能按时完成 MVP？
   ├── 需要调整范围吗？
   └── 工具：每周五的自我回顾

关键速度指标：

1. 任务完成速度（Tasks/Day）
   ├── 目标：2-4 个/天
   ├── 计算：本周完成的任务数 / 工作天数
   ├── 趋势：应该保持稳定或略有提升
   └── 如果持续低于 2 个/天，需要分析原因

2. 代码提交频率（Commits/Day）
   ├── 目标：3-5 个/天
   ├── 计算：git log --oneline --since="today" | wc -l
   ├── 每个任务至少 1 个 commit
   └── 频率过低可能意味着任务粒度太大

3. 测试通过率（Pass Rate）
   ├── 目标：> 95%
   ├── 计算：通过的测试数 / 总测试数
   ├── 如果低于 90%，需要停下来修复
   └── 不要积累失败的测试

4. 构建成功率（Build Success Rate）
   ├── 目标：100%
   ├── 每次 push 都应该构建成功
   ├── 构建失败 = 立即修复
   └── CI 红灯不过夜

5. 阻塞时间比（Block Time Ratio）
   ├── 目标：< 15%
   ├── 计算：被阻塞的时间 / 总工作时间
   ├── 如果超过 20%，需要改变策略
   └── 记录每次阻塞的原因和持续时间

每周五花 30 分钟做回顾：

Week [N] 回顾

完成情况
├── 计划完成任务数：[N]
├── 实际完成任务数：[N]
└── 完成率：[N]%

本周亮点
├── [最大的进展是什么]
└── [学到了什么新东西]

本周挑战
├── [遇到的最大困难]
└── [如何解决的 / 还没解决]

下周计划
├── 优先任务：[列出 top 5]
├── 需要解决的阻塞：[列出]
└── 需要调整的 Spec：[列出]

速度指标
├── 任务完成速度：[N] 个/天
├── 测试通过率：[N]%
└── 阻塞时间比：[N]%

请分析我的项目开发进度：

项目：[项目名]
当前周次：Week [3/4]
总 Spec 任务数：[N]
已完成任务数：[N]
本周完成任务数：[N]
剩余工作日：[N]

本周遇到的主要问题：
1. [问题 1]
2. [问题 2]

请帮我：
1. 评估当前进度是否健康
2. 预测能否按时完成 MVP
3. 如果有风险，建议调整策略
4. 建议下周的重点任务
5. 识别潜在的风险点

CodeLens tasks.md（Week 3-4 相关任务）：

- [x] 1. 认证模块（Week 2 已完成）
- [ ] 2. GitHub 集成
  - [ ] 2.1 GitHub App 注册和配置
  - [ ] 2.2 Webhook 接收端点
  - [ ] 2.3 PR diff 获取逻辑
  - [ ] 2.4 仓库连接 UI
- [ ] 3. AI 审查引擎
  - [ ] 3.1 Claude API 集成
  - [ ] 3.2 代码审查 Prompt 设计
  - [ ] 3.3 审查结果解析和存储
  - [ ] 3.4 审查评论生成
- [ ] 4. Dashboard
  - [ ] 4.1 审查统计卡片
  - [ ] 4.2 最近审查列表
  - [ ] 4.3 审查详情页
  - [ ] 4.4 代码 diff 展示组件
- [ ] 5. 设置模块
  - [ ] 5.1 审查规则配置
  - [ ] 5.2 通知偏好设置
  - [ ] 5.3 团队管理（基础版）
- [ ] 6. 支付集成
  - [ ] 6.1 Stripe 集成
  - [ ] 6.2 定价页面
  - [ ] 6.3 订阅管理
- [ ] 7. 邮件通知
  - [ ] 7.1 Resend 集成
  - [ ] 7.2 审查完成通知
  - [ ] 7.3 每周摘要邮件

Week 3 Day 1（周一）：GitHub 集成基础
├── 09:15-10:00  任务 2.1：GitHub App 注册和配置
│   ├── 在 GitHub 创建 App，配置权限和 Webhook URL
│   ├── 将 App 凭证添加到环境变量
│   └── ✅ 完成，commit: "feat(github): configure GitHub App credentials"
├── 10:00-11:30  任务 2.2：Webhook 接收端点
│   ├── 实现 /api/webhook/github 端点
│   ├── 验证 Webhook 签名
│   ├── 处理 pull_request 事件
│   └── ✅ 完成，commit: "feat(github): implement webhook receiver"
├── 11:30-12:00  代码审查 + 测试
│   ├── 审查 Webhook 签名验证逻辑
│   ├── 编写 Webhook 处理的单元测试
│   └── ✅ 所有测试通过
├── 13:00-14:30  任务 2.3：PR diff 获取逻辑
│   ├── 实现 GitHub API 调用获取 PR diff
│   ├── 解析 diff 格式，提取变更文件和代码
│   ├── 遇到问题：大 PR 的 diff 超过 API 限制
│   ├── 解决：分文件获取 diff，合并结果
│   └── ✅ 完成，commit: "feat(github): implement PR diff fetching"
├── 14:30-16:00  任务 2.4：仓库连接 UI
│   ├── 实现 GitHub App 安装引导页面
│   ├── 实现已连接仓库列表
│   ├── 实现连接/断开操作
│   └── ✅ 完成，commit: "feat(github): add repository connection UI"
├── 16:00-16:30  代码审查 + 测试
│   └── ✅ 4 个任务全部完成，所有测试通过
└── 16:30-17:00  更新 tasks.md，push 代码
    └── 今日完成：4 个任务 ✅

Week 3 Day 2（周二）：AI 审查引擎
├── 09:15-10:30  任务 3.1：Claude API 集成
│   ├── 实现 Claude API 客户端封装
│   ├── 配置 token 限制和重试逻辑
│   ├── 实现流式响应处理
│   └── ✅ 完成
├── 10:30-12:00  任务 3.2：代码审查 Prompt 设计
│   ├── 设计系统 prompt（角色、规则、输出格式）
│   ├── 设计用户 prompt（代码上下文、diff、语言）
│   ├── 测试不同代码场景的审查质量
│   ├── 迭代 3 次优化 prompt
│   └── ✅ 完成
├── 13:00-14:30  任务 3.3：审查结果解析和存储
│   ├── 定义审查结果数据模型
│   ├── 实现 AI 输出解析（JSON 格式）
│   ├── 实现结果存储到 Supabase
│   ├── 编写 PBT 测试：验证解析逻辑的健壮性
│   └── ✅ 完成
├── 14:30-16:00  任务 3.4：审查评论生成
│   ├── 实现将审查结果转换为 GitHub PR 评论
│   ├── 实现评论的严重程度标签（Critical/Warning/Info）
│   ├── 实现批量评论提交
│   └── ✅ 完成
└── 今日完成：4 个任务 ✅

Week 3 Day 3（周三）：Dashboard 核心
├── 任务 4.1：审查统计卡片 → ✅
├── 任务 4.2：最近审查列表 → ✅
├── 任务 4.3：审查详情页 → ✅（遇到 diff 展示问题，用了 1 小时解决）
└── 今日完成：3 个任务 ✅

Week 3 Day 4（周四）：Dashboard 完善 + 设置
├── 任务 4.4：代码 diff 展示组件 → ✅
├── 任务 5.1：审查规则配置 → ✅
├── 任务 5.2：通知偏好设置 → ✅
└── 今日完成：3 个任务 ✅

Week 3 Day 5（周五）：设置完善 + 集成测试
├── 任务 5.3：团队管理（基础版）→ ✅
├── 集成测试：完整的 PR 审查流程测试
├── Bug 修复：发现 Webhook 在并发时有竞态条件 → 修复
├── 周回顾：
│   ├── 本周完成：17 个任务
│   ├── 速度：3.4 个/天（超出预期）
│   ├── 测试通过率：98%
│   └── 主要挑战：大 PR diff 处理、并发竞态
└── 今日完成：1 个任务 + 集成测试 + Bug 修复 ✅

Week 4 Day 1（周一）：支付集成
├── 任务 6.1：Stripe 集成 → ✅（耗时较长，Webhook 配置复杂）
├── 任务 6.2：定价页面 → ✅
└── 今日完成：2 个任务 ✅

Week 4 Day 2（周二）：支付完善 + 邮件
├── 任务 6.3：订阅管理 → ✅
├── 任务 7.1：Resend 集成 → ✅
├── 任务 7.2：审查完成通知 → ✅
└── 今日完成：3 个任务 ✅

Week 4 Day 3（周三）：邮件 + 优化
├── 任务 7.3：每周摘要邮件 → ✅
├── 优化：审查响应时间优化（从 45 秒降到 20 秒）
├── 优化：Dashboard 加载性能优化
└── 今日完成：1 个任务 + 2 个优化 ✅

Week 4 Day 4（周四）：全功能集成 + Bug 修复
├── 全功能端到端测试
├── 修复 5 个 Bug：
│   ├── Stripe Webhook 签名验证在生产环境失败
│   ├── 长文件名在 diff 展示中溢出
│   ├── 免费用户超出配额时没有提示
│   ├── 邮件模板在 Outlook 中显示异常
│   └── 移动端侧边栏无法关闭
└── 今日完成：5 个 Bug 修复 ✅

Week 4 Day 5（周五）：收尾 + 回顾
├── 最终集成测试：所有核心流程通过
├── 代码清理：删除 TODO 注释、清理 console.log
├── 更新 tasks.md：所有任务标记完成
├── 两周回顾：
│   ├── 总完成任务：27 个 Spec 任务 + 7 个 Bug 修复
│   ├── 平均速度：2.7 个任务/天
│   ├── 测试覆盖率：72%
│   ├── 总 commit 数：34 个
│   └── 代码行数：约 8,000 行（含测试）
└── 输出：功能完整的 MVP ✅

成功因素：
1. Spec 先行：所有任务在开始前就定义清楚，避免了范围蔓延
2. 节奏稳定：每天 2-4 个任务，没有过度加班
3. 及时处理阻塞：大 PR diff 问题在 1 小时内解决
4. 测试驱动：每个任务后都运行测试，Bug 在早期发现
5. Git 纪律：每个任务一个 commit，历史清晰可追溯

关键决策：
├── Day 3 遇到 diff 展示问题 → 用开源库替代自己实现
├── Day 5 发现竞态条件 → 立即修复而非延后
├── Week 4 Day 1 Stripe 集成复杂 → 只完成 2 个任务，不强求
└── Week 4 Day 3 提前优化 → 因为审查响应时间影响用户体验

时间分配统计：
├── 编码（AI 生成 + 审查）：60%
├── 测试：15%
├── Bug 修复：10%
├── 规划和回顾：10%
└── 阻塞和研究：5%