17a - Spec-Driven 工作流全景

Spec（source of truth）+ AI Agent（草稿生成）+ Human Review（最终审查）= 生产级代码

Spec 文档体系
├── requirements.md    ← 用户故事 + 验收标准（做什么）
├── design.md          ← 技术设计 + 架构决策（怎么做）
└── tasks.md           ← 任务拆分 + 执行顺序（分几步做）

┌─────────────────────────────────────────────────────────────────┐
│                  Spec-Driven Agentic Workflow                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Phase 1: 规划（"15 分钟瀑布"）                                  │
│  ┌────────────┐   ┌────────────┐   ┌────────────┐              │
│  │  AI 采访   │ → │  生成 Spec  │ → │ Plan Mode  │              │
│  │  理清需求   │   │ (source of │   │ (只读分析   │              │
│  │  明确边界   │   │   truth)   │   │  不改文件)  │              │
│  └────────────┘   └────────────┘   └────────────┘              │
│        ↕ 人工确认       ↕ 人工审查       ↕ 人工批准              │
│                         ↓                                       │
│  Phase 2: 微任务执行                                             │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐                    │
│  │ Task 1   │ → │ Task 2   │ → │ Task 3   │ → ...             │
│  │ 实现+测试 │   │ 实现+测试 │   │ 实现+测试 │                    │
│  └──────────┘   └──────────┘   └──────────┘                    │
│       ↕               ↕               ↕                         │
│    人工审查         人工审查         人工审查                      │
│    git commit      git commit      git commit                   │
│                         ↓                                       │
│  Phase 3: 上下文工程                                             │
│  ┌──────────────────────────────────────────────┐               │
│  │  贯穿全程的上下文管理                           │               │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐     │               │
│  │  │ 精确选择  │ │ MCP 连接 │ │ Steering │     │               │
│  │  │ 相关文件  │ │ 外部工具  │ │ 规则约束  │     │               │
│  │  └──────────┘ └──────────┘ └──────────┘     │               │
│  │  ┌──────────┐ ┌──────────┐                   │               │
│  │  │ 设计文档  │ │ 测试反馈  │                   │               │
│  │  │ 引用     │ │ 循环     │                   │               │
│  │  └──────────┘ └──────────┘                   │               │
│  └──────────────────────────────────────────────┘               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

提示词模板：

我要实现 [功能描述]。请扮演一位资深产品经理，
通过提问帮我理清以下方面：
1. 核心用户场景（谁在什么情况下使用）
2. 功能边界（做什么，不做什么）
3. 非功能需求（性能、安全、可用性）
4. 依赖和约束（现有系统、技术栈限制）

每次只问 2-3 个问题，等我回答后再继续。

提示词模板：

基于我们刚才的讨论，生成一份技术规格文档，包含：

## 1. 概述（2-3 句话）
## 2. 功能需求
  - 用户故事（As a... I want... So that...）
  - 每个故事的验收标准（WHEN... THEN...）
## 3. 技术设计
  - 架构方案（含 Mermaid 图）
  - 数据模型
  - API 设计
  - 关键算法
## 4. 正确性属性
  - 系统必须满足的不变量
## 5. 任务拆分
  - 按依赖顺序排列
  - 每个任务预估 1-2 小时工作量

# Claude Code 中使用 Plan Mode
$ claude --plan "分析当前代码库架构，基于 SPEC.md 提出实现计划，
  标注哪些现有模块需要修改，哪些需要新建"
 
# Kiro 中
# Spec 的 design.md 自动包含对现有代码库的分析
# 通过 #File 和 #Folder 引用相关代码

从 tasks.md 中选择下一个未完成的任务。
确保其依赖任务已完成。

提示词模板：

请执行 Task [编号]：[任务标题]。

参考文档：
- design.md 中的 [相关章节]
- 现有代码 [相关文件路径]

要求：
1. 只实现这一个任务，不要做其他任务
2. 遵循 steering 文件中的编码规范
3. 为新增功能编写单元测试
4. 确保所有现有测试仍然通过

审查清单：
□ 代码是否符合 design.md 中的设计？
□ 是否有安全问题（SQL 注入、XSS、密钥泄露）？
□ 是否有性能问题（N+1 查询、内存泄漏）？
□ 测试是否覆盖了验收标准？
□ 是否引入了不必要的依赖？
□ 代码是否可读、可维护？

# 审查通过后
git add .
git commit -m "feat: Task 3.1 - 实现文件哈希计算函数"
 
# 标记任务完成，进入下一个任务

❌ 错误做法：
"请实现整个同步引擎"
→ AI 生成大量代码，质量不可控，上下文漂移严重

✅ 正确做法：
"请实现 Task 3.1：文件哈希计算函数"
→ 聚焦、可审查、可测试、可回滚

原则：只给 AI 看它需要的文件，不多不少。

✅ 好的上下文：
"参考 src/sync/hash.ts 和 src/types/index.ts，
 实现 src/sync/diff.ts 中的差异计算函数"

❌ 差的上下文：
"看看整个 src 目录，帮我实现差异计算"
→ 上下文噪音太多，AI 容易分心

// .kiro/settings/mcp.json 示例
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/github-mcp-server"],
      "env": { "GITHUB_TOKEN": "your-token" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/postgres-mcp-server"],
      "env": { "DATABASE_URL": "postgresql://..." }
    }
  }
}

<!-- .kiro/steering/coding-standards.md -->
# 编码规范
 
## 通用规则
- 所有公共函数必须有文档注释
- 错误处理不能用 try-catch 吞掉异常
- 不允许使用 any 类型（TypeScript）
 
## 测试规范
- 每个模块必须有单元测试
- 核心逻辑必须有 Property-Based Testing
- 测试文件与源文件同目录

你的项目类型是？
├── 个人项目/原型 → Kiro（免费版）或 Cursor
├── 中小团队生产项目
│   ├── 偏好 GUI → Kiro Pro 或 Cursor Pro
│   └── 偏好终端 → Claude Code
├── 企业级项目
│   ├── 需要审计合规 → Augment Code
│   └── 已有 GitHub 生态 → GitHub Copilot Business
└── 开源项目 → Claude Code + Kiro 免费版

任务复杂度评估：
├── 简单（样板代码、CRUD、格式转换）
│   → Claude Haiku 3.5 或 GPT-4o-mini（低成本高速）
├── 中等（功能实现、测试编写、重构）
│   → Claude Sonnet 4（最佳性价比）
├── 复杂（架构设计、跨模块重构、算法设计）
│   → Claude Opus 4 或 Grok 4
└── 超长上下文（大型代码库分析、长文档处理）
    → Gemini 2.5 Pro（1M+ tokens）

模型选择决策提示词：

我正在做 [任务描述]。
代码库规模：[文件数/行数]
任务复杂度：[简单/中等/复杂]
预算敏感度：[高/中/低]
需要的上下文量：[少量文件/多文件/整个代码库]

请推荐最适合的模型，并说明理由。

Level 1: 代码补全（Copilot 模式）
  ↓ 效率提升 10-20%，但不改变流程
Level 2: Vibe Coding（对话式生成）
  ↓ 效率提升 30-50%，但质量不稳定
Level 3: Spec-Driven（结构化 Agent）
  ↓ 效率提升 50-70%，质量可控
Level 4: 全自主工厂（Dark Factory）
  → 效率提升 80%+，人类只审批结果

项目生命周期中的模式切换：

1. 创意探索阶段 → Vibe Coding
   "帮我快速搭一个文件同步工具的原型"

2. 方案确认后 → 切换到 Spec-Driven
   "基于原型验证的结果，创建正式的 Spec"

3. 生产开发 → 严格 Spec-Driven
   "按 tasks.md 逐个执行任务"

4. 小修小补 → 回到 Vibe Coding
   "修复这个 CSS 对齐问题"

70% — AI 高效处理的部分：
├── 样板代码（CRUD、DTO、Schema、配置文件）
├── 标准模式实现（认证、分页、缓存、日志）
├── 测试用例生成（单元测试、集成测试骨架）
├── 文档生成（API 文档、README、注释）
├── 代码重构（提取函数、重命名、格式化）
├── 类型定义和接口声明
├── 数据库迁移文件
└── CI/CD 配置

30% — 人类不可替代的部分：
├── 架构决策（选择哪种方案、权衡取舍）
├── 边缘场景处理（AI 容易遗漏的异常路径）
├── 性能优化（需要 profiling 和实测数据）
├── 安全审查（AI 可能引入的漏洞）
├── 用户体验细节（微交互、动画、手感）
├── 业务逻辑验证（AI 不理解业务上下文）
├── 依赖评估（库的安全性、维护状态、许可证）
└── 技术债管理（何时重构、何时妥协）

没有 Spec 时 AI 的 70%：
→ 能跑但不一致的代码，需要大量人工修正
→ 实际有效贡献可能只有 40-50%

有 Spec 时 AI 的 70%：
→ 符合设计规范的代码，人工只需微调
→ 实际有效贡献可达 65-70%

<!-- 通过 Steering 规则预防常见问题 -->
# 安全规则
- 所有用户输入必须经过验证和清洗
- 数据库查询必须使用参数化查询
- API 密钥不得硬编码在源代码中
- 所有 HTTP 端点必须有认证检查
 
# 代码质量规则
- 函数不超过 50 行
- 圈复杂度不超过 10
- 不使用 console.log 作为日志方案

传统测试：验证特定输入的特定输出（example-based）
PBT：验证所有输入都满足某个属性（property-based）

示例：
- 属性："排序后的数组长度等于原数组长度"
- 属性："加密后解密应得到原文"
- 属性："同步后本地和远程文件内容一致"

PBT 能自动发现 AI 代码中的边缘场景 bug，
减少人类需要手动检查的 30% 中的工作量。

审查 AI 生成代码的提示词：

请审查以下代码，重点检查：
1. 是否符合 design.md 中 [章节] 的设计
2. 安全性：SQL 注入、XSS、密钥泄露、权限绕过
3. 性能：N+1 查询、内存泄漏、不必要的计算
4. 边缘场景：空输入、超大输入、并发访问、网络中断
5. 可维护性：命名清晰、职责单一、适当抽象

代码：
[粘贴代码]

请按严重程度排序列出问题，并给出修复建议。

开发者 ←→ AI Agent
   ↓
  Spec（自己写 + AI 辅助）
   ↓
  逐任务执行 + 自我审查
   ↓
  git commit + 自动测试

产品经理 → Spec 初稿
   ↓
技术负责人 → Spec 审查 + 技术设计
   ↓
开发者 ←→ AI Agent → 代码草稿
   ↓
Code Review（团队成员交叉审查）
   ↓
CI/CD → 自动测试 → 部署

产品团队 → PRD
   ↓
架构师 → 技术 Spec + ADR
   ↓
多个开发者 ←→ 各自的 AI Agent
   ↓
自动化 Code Review + 安全扫描
   ↓
QA 团队 → 验收测试
   ↓
DevOps → 自动部署

人类 → 高层 Spec（Markdown 格式）
   ↓
AI 系统 → 自动分解任务
   ↓
AI Agent 集群 → 并行实现
   ↓
AI 测试 → 自动验证行为场景
   ↓
人类 → 审批最终产出物

Day 1 上午：规划（约 30 分钟）
├── 在 Kiro 中创建 spec "rustsync-tool"
├── AI 生成 requirements.md → 审查确认 12 个用户故事
├── AI 生成 design.md → 审查确认架构设计（Tauri + React）
└── AI 生成 tasks.md → 确认 25 个实现任务

Day 1 下午：核心模块（约 4 小时）
├── Task 1: 项目初始化（Tauri + React + TypeScript）
├── Task 2: 配置管理模块（TOML 配置读写）
├── Task 3: 文件监控模块（inotify/FSEvents 封装）
└── 每个任务：AI 生成 → 人工审查 → 测试 → git commit

Day 2：同步引擎（约 6 小时）
├── Task 4: 差异计算引擎（基于文件哈希的增量检测）
├── Task 5: 百度网盘 API 集成（OAuth + 文件上传/下载）
├── Task 6: 同步调度器（队列管理 + 并发控制）
└── Task 7: 冲突检测与解决（时间戳 + 用户选择）

Day 3：UI 层（约 5 小时）
├── Task 8-15: React 组件实现
│   ├── 文件夹列表、同步状态栏、设置面板
│   ├── 同步日志、同步报告、添加文件夹对话框
│   └── 通过 Steering 规则确保 CSS Modules + 函数式组件
└── 通过 MCP 读取设计稿辅助 UI 实现

Day 4：测试与打磨（约 4 小时）
├── Task 16-20: 单元测试 + Property-Based Testing
├── Task 21-23: 集成测试
└── Task 24-25: 打包与发布配置

<!-- .kiro/steering/coding-standards.md -->
# RustSync 编码规范
 
## Rust 代码规范
- 使用 thiserror 处理错误，禁止 unwrap()
- 所有公共函数必须有文档注释
- 使用 clippy 的所有默认 lint
- 异步代码使用 tokio
 
## TypeScript 代码规范
- 使用 CSS Modules，不用内联样式
- 组件使用函数式组件 + hooks
- 类型定义集中在 types/index.ts
- 状态管理使用 React hooks，不引入额外状态库
 
## 测试规范
- 每个模块必须有单元测试
- 核心逻辑必须有 Property-Based Testing
- 测试文件与源文件同目录，使用 .test.ts/.test.rs 后缀