17b - 15 分钟瀑布规划法

传统瀑布规划                          15 分钟瀑布规划
┌──────────────────┐                 ┌──────────────────┐
│ 需求分析（2-5 天）│                 │ AI 采访理清需求   │ ← 5 分钟
├──────────────────┤                 ├──────────────────┤
│ 系统设计（3-7 天）│                 │ AI 生成 Spec 文档 │ ← 5 分钟
├──────────────────┤                 ├──────────────────┤
│ 技术评审（1-2 天）│                 │ Plan Mode 分析   │ ← 3 分钟
├──────────────────┤                 ├──────────────────┤
│ 任务拆分（1-2 天）│                 │ 自动任务分解     │ ← 2 分钟
└──────────────────┘                 └──────────────────┘
     总计：7-16 天                        总计：~15 分钟

Step 1: 创建 Spec（~5-8 分钟）
  ├── AI 采访：理清需求边界
  ├── 生成 requirements.md：用户故事 + 验收标准
  ├── 生成 design.md：技术设计 + 架构决策
  └── 人工审查：确认方向正确

Step 2: Plan Mode 分析（~3-5 分钟）
  ├── 只读分析现有代码库
  ├── 识别需要修改的模块
  ├── 评估技术风险
  └── 人工确认实现计划

Step 3: 任务分解（~2-3 分钟）
  ├── 生成 tasks.md：按依赖顺序排列
  ├── 每个任务预估 1-2 小时工作量
  ├── 标注任务间的依赖关系
  └── 人工确认任务列表

1. 打开 Kiro IDE
2. 在 Kiro 面板中点击 Specs 下的 "+" 按钮
   （或通过命令面板 Ctrl+Shift+P → "Kiro: Create New Spec"）
3. 在对话框中描述你要构建的功能

示例输入：

"我要实现一个文件同步引擎，支持本地文件夹与百度网盘之间的
增量同步。需要支持文件变更检测、冲突处理和断点续传。
技术栈是 Tauri（Rust 后端 + React 前端）。"

# 生成的 requirements.md 示例片段
 
### Requirement 1: 文件变更检测
 
**User Story:** As a 用户, I want 系统自动检测本地文件变更,
so that 变更能及时同步到云端。
 
#### Acceptance Criteria
 
1. WHEN a file is created in a monitored folder,
   THE system SHALL detect the change within 2 seconds
2. WHEN a file is modified,
   THE system SHALL compute the file hash and compare
   with the last known hash
3. WHEN a file is deleted,
   THE system SHALL mark it as pending deletion
   in the sync queue

# 生成的 design.md 示例片段
 
## Architecture
 
### 系统架构图
 
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  React UI   │ ←→  │  Tauri Bridge │ ←→  │  Rust Core  │
│  (前端)      │     │  (IPC 通信)   │     │  (后端引擎)  │
└─────────────┘     └──────────────┘     └─────────────┘
                                               │
                    ┌──────────────────────────┤
                    ↓              ↓            ↓
              ┌──────────┐  ┌──────────┐  ┌──────────┐
              │ 文件监控  │  │ 差异计算  │  │ 同步调度  │
              │ Module   │  │ Module   │  │ Module   │
              └──────────┘  └──────────┘  └──────────┘
 
### Components
 
- **FileWatcher**: 基于 notify crate 的文件系统监控
- **DiffEngine**: 基于文件哈希的增量差异计算
- **SyncScheduler**: 带优先级队列的同步任务调度器
- **BaiduPanClient**: 百度网盘 API 封装

# 生成的 tasks.md 示例片段
 
## Tasks
 
- [ ] 1. 项目初始化
  - [ ] 1.1 创建 Tauri + React 项目骨架
  - [ ] 1.2 配置 Rust 依赖（notify, tokio, serde）
  - [ ] 1.3 配置 TypeScript 依赖和构建工具
 
- [ ] 2. 配置管理模块
  - [ ] 2.1 定义配置数据结构
  - [ ] 2.2 实现 TOML 配置读写
  - [ ] 2.3 实现配置变更监听
 
- [ ] 3. 文件监控模块
  - [ ] 3.1 实现文件系统事件监听
  - [ ] 3.2 实现文件哈希计算
  - [ ] 3.3 实现变更事件去重和节流

提示词模板：

我要实现 [功能名称]。

背景信息：
- 项目类型：[Web 应用/桌面应用/CLI 工具/移动应用]
- 技术栈：[具体技术栈]
- 现有代码库：[有/无，如有请描述规模和架构]
- 目标用户：[用户画像]
- 性能要求：[具体指标，如响应时间 < 200ms]
- 安全要求：[认证方式、数据加密等]

核心功能：
1. [功能点 1]
2. [功能点 2]
3. [功能点 3]

明确不做的事情：
- [排除项 1]
- [排除项 2]

请生成详细的 Spec，包含用户故事、验收标准、技术设计和任务拆分。

# 在项目根目录创建 Spec 文件
touch SPEC.md

# 启动 Claude Code，进入 Plan Mode
$ claude
 
# 在对话中使用以下提示词

提示词模板（需求采访）：

我要实现 [功能描述]。请扮演一位资深产品经理和架构师，
通过提问帮我理清以下方面：

1. 核心用户场景（谁在什么情况下使用）
2. 功能边界（做什么，不做什么）
3. 非功能需求（性能、安全、可用性）
4. 依赖和约束（现有系统、技术栈限制）
5. 成功标准（怎样算"做完了"）

每次只问 2-3 个问题，等我回答后再继续。
当你认为需求已经足够清晰时，告诉我你准备好生成 Spec 了。

提示词模板（Spec 文档生成）：

基于我们刚才的讨论，生成一份完整的技术规格文档（SPEC.md），
包含以下结构：

## 1. 概述
[2-3 句话说明项目目标]

## 2. 功能需求
对每个功能点：
- 用户故事（As a... I want... So that...）
- 验收标准（WHEN... THEN... 格式）

## 3. 非功能需求
- 性能指标
- 安全要求
- 可用性要求

## 4. 技术设计
- 架构方案（含 ASCII 或 Mermaid 图）
- 数据模型（含字段类型和关系）
- API 设计（端点、请求/响应格式）
- 关键算法（伪代码或流程图）

## 5. 正确性属性（Properties）
- 列出系统必须满足的不变量
- 例如："同步后，本地文件和远程文件的哈希值必须一致"

## 6. 任务拆分
- 按依赖顺序排列
- 每个任务预估 1-2 小时工作量
- 标注任务间的依赖关系

请确保每个验收标准都是可测试的。

# Claude Code 会将内容写入 SPEC.md
# 审查后，用 Plan Mode 验证
$ claude --plan "审查 SPEC.md 的完整性和一致性，
  检查是否有遗漏的需求或矛盾的设计决策"

<!-- .cursorrules -->
# 项目规范
 
## Spec-Driven 工作流规则
- 所有新功能必须先创建 SPEC.md
- SPEC.md 必须包含用户故事、验收标准、技术设计
- 代码实现必须引用 SPEC.md 中的具体需求编号
- 每个 PR 必须说明对应的 Spec 任务编号
 
## 编码规范
[项目特定的编码规范]

在 Cursor Composer（Ctrl+I）中输入：

@SPEC.md 请基于以下需求生成完整的技术规格文档：

需求：[详细描述]

参考现有代码：
@src/main.ts
@src/types/index.ts
@package.json

请遵循 .cursorrules 中定义的 Spec 格式。

Cursor 的优势在于可以用 @ 引用现有代码，
让 AI 基于实际代码库生成更准确的 Spec：

@src/ 分析现有代码结构，然后更新 @SPEC.md 中的
技术设计部分，确保新功能与现有架构兼容。

# 克隆 Spec Kit 模板
npx spec-kit init
 
# 或手动创建目录结构
mkdir -p .spec
touch .spec/spec.md .spec/plan.md .spec/tasks.md

<!-- .spec/spec.md -->
# Feature: 文件同步引擎
 
## Goal
实现本地文件夹与云存储之间的增量同步
 
## Requirements
1. 文件变更检测（创建、修改、删除）
2. 增量同步（只传输变更部分）
3. 冲突检测与解决
4. 断点续传
 
## Constraints
- 技术栈：Rust + React（Tauri）
- 性能：单文件同步延迟 < 5 秒
- 安全：传输加密，本地配置加密存储

# 使用 Claude Code 基于 Spec 生成计划
$ claude "基于 .spec/spec.md 生成详细的技术计划，
  写入 .spec/plan.md"
 
# 然后生成任务列表
$ claude "基于 .spec/plan.md 生成可执行的任务列表，
  写入 .spec/tasks.md，每个任务 1-2 小时工作量"

提示词模板（Spec 质量审查）：

请审查以下 Spec 文档，检查：

1. 完整性：是否覆盖了所有核心功能？是否遗漏了边缘场景？
2. 一致性：需求之间是否有矛盾？设计是否与需求对齐？
3. 可测试性：每个验收标准是否可以编写自动化测试？
4. 可行性：技术方案是否可行？是否有更简单的替代方案？
5. 明确性：是否有模糊的描述需要澄清？

Spec 文档：
[粘贴 Spec 内容]

请按优先级列出发现的问题，并给出改进建议。

Plan Mode 的输入和输出：

输入：
├── Spec 文档（requirements + design）
├── 现有代码库
├── 配置文件（package.json, Cargo.toml 等）
└── 开发者的补充说明

输出：
├── 代码库架构理解
├── 需要修改的模块清单
├── 潜在风险和技术债
├── 建议的实现顺序
└── 预估的工作量

# 方式 1：命令行参数
$ claude --plan "分析当前代码库，基于 SPEC.md 提出实现计划"
 
# 方式 2：在对话中切换
# 按 Shift+Tab 切换到 Plan Mode
# 或输入 /plan 命令

提示词模板（代码库全景分析）：

请在 Plan Mode 下分析当前代码库，回答以下问题：

1. 项目结构：
   - 主要目录和模块划分
   - 入口文件和核心模块
   - 依赖关系图

2. 架构模式：
   - 使用了哪些设计模式？
   - 数据流是怎样的？
   - 错误处理策略是什么？

3. 基于 SPEC.md 的实现评估：
   - 哪些现有模块可以复用？
   - 哪些模块需要修改？
   - 哪些功能需要从零开始？

4. 风险识别：
   - 现有代码中有哪些技术债？
   - 新功能可能与哪些现有功能冲突？
   - 有哪些性能瓶颈需要注意？

请不要修改任何文件，只进行分析。

提示词模板（针对特定模块的深度分析）：

请分析 [模块路径] 的实现细节：

1. 这个模块的职责是什么？
2. 它依赖哪些其他模块？
3. 它暴露了哪些公共 API？
4. 基于 SPEC.md 中的 [需求编号]，
   这个模块需要做哪些修改？
5. 修改的风险等级是？（高/中/低）
6. 建议的修改策略是？

请只分析，不要修改代码。

Plan Mode 输出示例：

## 代码库分析结果

### 项目结构
src/
├── main.ts          # 应用入口
├── config/          # 配置管理（可复用）
├── sync/            # 同步引擎（需要大幅修改）
│   ├── watcher.ts   # 文件监控（可复用，需扩展）
│   ├── diff.ts      # 差异计算（需要重写）
│   └── scheduler.ts # 调度器（需要新建）
└── ui/              # React 组件（需要新建同步状态面板）

### 实现计划

#### 阶段 1：基础设施（Task 1-3）
- 修改 config/ 添加同步配置项
- 扩展 watcher.ts 支持递归目录监控
- 风险：低

#### 阶段 2：核心引擎（Task 4-7）
- 重写 diff.ts 使用增量哈希算法
- 新建 scheduler.ts 实现优先级队列
- 新建 cloud-client.ts 封装云存储 API
- 风险：中（API 集成可能有兼容性问题）

#### 阶段 3：UI 层（Task 8-12）
- 新建同步状态面板组件
- 新建冲突解决对话框
- 风险：低

在 Kiro 中，Plan Mode 是隐式的：

1. 创建 Spec 时，Kiro 自动扫描项目结构
2. design.md 中的架构设计基于实际代码库
3. tasks.md 中的任务考虑了现有模块的修改

你也可以显式引导分析：
- 使用 #File 引用特定文件让 AI 重点分析
- 使用 #Folder 引用整个目录
- 在 Spec 描述中提及现有模块

第 1 轮：全景扫描
"分析整个项目结构，给出高层架构理解"

第 2 轮：重点深入
"基于第 1 轮的分析，深入分析 [关键模块]，
 评估实现 [具体需求] 的可行性"

第 3 轮：风险评估
"基于前两轮分析，列出实现计划中的
 Top 5 风险和缓解策略"

好的任务分解遵循 SMART 原则：

S - Specific（具体）：明确要做什么，不含糊
M - Measurable（可衡量）：有明确的完成标准
A - Achievable（可实现）：1-2 小时内可完成
R - Relevant（相关）：与 Spec 中的需求直接对应
T - Time-bound（有时限）：预估工作量

示例：
❌ "实现同步功能"（太大、太模糊）
✅ "Task 3.1：实现基于 SHA-256 的文件哈希计算函数，
    输入文件路径，输出 64 字符哈希字符串，
    包含单元测试，预估 1 小时"

提示词模板（任务分解）：

基于以下 Spec 文档，生成一份详细的任务列表。

要求：
1. 每个任务 1-2 小时工作量
2. 按依赖顺序排列（被依赖的任务排在前面）
3. 每个任务包含：
   - 任务编号和标题
   - 具体要做什么（2-3 句话）
   - 对应的 Spec 需求编号
   - 依赖的前置任务
   - 完成标准（怎样算"做完了"）
4. 使用 Markdown checkbox 格式

Spec 文档：
[粘贴 Spec 内容]

请生成 tasks.md。

提示词模板（任务依赖分析）：

请分析以下任务列表的依赖关系，生成依赖图：

[粘贴任务列表]

要求：
1. 用 ASCII 图或 Mermaid 图展示依赖关系
2. 标注关键路径（最长依赖链）
3. 标注可以并行执行的任务组
4. 如果发现循环依赖，提出解决方案

任务列表审查清单：

□ 任务粒度是否合适？（每个 1-2 小时）
□ 依赖顺序是否正确？（被依赖的任务在前）
□ 是否覆盖了 Spec 中的所有需求？
□ 每个任务的完成标准是否明确？
□ 是否有遗漏的任务？（如测试、文档、配置）
□ 是否有可以并行的任务？（标注出来提高效率）
□ 总工作量预估是否合理？

# 增强版 tasks.md 示例
 
## Tasks
 
- [ ] 1. 项目初始化
  - [ ] 1.1 创建 Tauri + React 项目骨架
    - 依赖：无
    - 预估：30 分钟
    - 风险：低
    - _Requirements: 1.1_
  - [ ] 1.2 配置 Rust 依赖
    - 依赖：1.1
    - 预估：30 分钟
    - 风险：低（版本兼容性需验证）
    - _Requirements: 1.1_
 
- [ ] 2. 文件监控模块
  - [ ] 2.1 实现文件系统事件监听
    - 依赖：1.1, 1.2
    - 预估：1.5 小时
    - 风险：中（跨平台兼容性）
    - _Requirements: 2.1, 2.2_
  - [ ] 2.2 实现文件哈希计算
    - 依赖：1.2
    - 预估：1 小时
    - 风险：低
    - _Requirements: 2.3_

Layer 1: 数据层（类型定义、数据模型、数据库迁移）
Layer 2: 业务逻辑层（核心算法、服务函数）
Layer 3: API 层（端点定义、中间件、验证）
Layer 4: UI 层（组件、页面、样式）
Layer 5: 集成层（测试、配置、部署）

Feature A: 用户认证
  ├── Task A.1: 注册接口
  ├── Task A.2: 登录接口
  └── Task A.3: 认证中间件

Feature B: 文件管理
  ├── Task B.1: 文件上传
  ├── Task B.2: 文件列表
  └── Task B.3: 文件删除

Phase 1: 高风险任务（先做，早发现问题）
  ├── 第三方 API 集成验证
  ├── 核心算法原型
  └── 性能瓶颈验证

Phase 2: 中风险任务
  ├── 业务逻辑实现
  └── 数据模型完善

Phase 3: 低风险任务（最后做，确定性高）
  ├── UI 组件实现
  ├── 文档编写
  └── 部署配置

在 Kiro 中创建新 Spec，输入描述：

"我要开发一个桌面文件同步工具 RustSync，
使用 Tauri（Rust 后端 + React 前端）。

核心功能：
1. 监控本地文件夹的文件变更
2. 计算文件差异，只同步变更部分
3. 通过百度网盘 API 上传/下载文件
4. 检测和处理同步冲突
5. 支持 .gitignore 风格的忽略规则
6. 提供同步进度和日志的 UI

不做的事情：
- 不支持实时协作编辑
- 不支持多云存储（只支持百度网盘）
- 不做移动端"

Kiro 在生成 design.md 时自动分析了项目结构。

design.md 中的关键决策：
- 文件监控：使用 notify crate（跨平台）
- 差异计算：基于 SHA-256 文件哈希
- 同步调度：带优先级的异步任务队列
- 前端状态：React hooks + CSS Modules
- IPC 通信：Tauri 的 invoke 机制

审查后调整了一个设计决策：
将冲突解决策略从"自动选择最新版本"
改为"提示用户选择"，因为自动策略可能导致数据丢失。

Kiro 生成的 tasks.md 包含 25 个任务，分为 5 个阶段：

阶段 1：基础设施（Task 1-3，约 3 小时）
├── 项目初始化
├── 配置管理模块
└── 类型定义

阶段 2：核心引擎（Task 4-7，约 8 小时）
├── 文件监控模块
├── 差异计算引擎
├── 百度网盘 API 集成
└── 同步调度器

阶段 3：高级功能（Task 8-11，约 6 小时）
├── 冲突检测与解决
├── 忽略规则引擎
├── 断点续传
└── 日志系统

阶段 4：UI 层（Task 12-19，约 8 小时）
├── 布局组件
├── 文件夹列表
├── 同步状态栏
├── 设置面板
├── 同步日志
├── 同步报告
├── 添加文件夹对话框
└── 百度网盘授权组件

阶段 5：测试与打磨（Task 20-25，约 6 小时）
├── 单元测试
├── Property-Based Testing
├── 集成测试
├── 错误处理完善
├── 性能优化
└── 打包配置

审查后合并了两个过小的任务，最终确认 25 个任务。
总预估工作量：约 31 小时（4 个工作日）。