17c - 微任务执行与人工审查

功能需求："实现文件同步引擎"

❌ 作为单个任务交给 AI：
   → 生成数千行代码，质量不可控，上下文漂移严重

✅ 拆分为微任务：
   Task 3.1: 实现文件哈希计算函数
   Task 3.2: 实现文件差异比较模块
   Task 3.3: 实现增量同步算法
   Task 3.4: 实现冲突检测逻辑
   Task 3.5: 实现冲突解决策略
   → 每个任务聚焦、可审查、可测试

┌─────────────────────────────────────────────────────────────┐
│              微任务执行循环（每个任务重复一次）                 │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ① 阅读任务          ② 指示 AI 执行        ③ AI 生成代码    │
│  ┌──────────┐       ┌──────────┐          ┌──────────┐     │
│  │ 读任务描述│  →    │ 精确 Prompt│  →      │ 代码 + 测试│    │
│  │ 读设计文档│       │ 限定范围  │          │ 文档变更   │     │
│  └──────────┘       └──────────┘          └──────────┘     │
│                                                ↓            │
│  ⑥ 标记完成          ⑤ 运行测试            ④ 人工审查       │
│  ┌──────────┐       ┌──────────┐          ┌──────────┐     │
│  │ git commit│  ←   │ 单元测试  │  ←       │ 逐行审查  │     │
│  │ 进入下一个│       │ 集成测试  │          │ 安全/性能  │     │
│  └──────────┘       └──────────┘          └──────────┘     │
│                                                             │
│  如果审查不通过 → 回到 ② 让 AI 修正 → 再次审查（最多 2-3 轮） │
└─────────────────────────────────────────────────────────────┘

# 在 Kiro 中：
# 打开 Spec 面板，点击要执行的任务
# Kiro 自动加载相关的 requirements 和 design 上下文

# 在 Claude Code 中：
$ claude "请阅读 SPEC.md 中 Task 3.1 的描述和相关设计，
  告诉我你理解的实现要求和验收标准"

# ❌ 错误的指示（范围太大）
"请实现整个同步引擎"

# ❌ 错误的指示（太模糊）
"帮我写个文件处理的功能"

# ✅ 正确的指示（精确、有边界）
"请执行 Task 3.1：实现文件哈希计算函数。
 参考 design.md 中第 3 节的哈希算法设计。
 要求：
 - 使用 SHA-256 算法
 - 支持大文件流式计算（不一次性读入内存）
 - 包含单元测试
 - 只实现这一个任务，不要做其他任务"

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

参考文档：
- design.md 中的 [相关章节]
- requirements.md 中的验收标准 [AC 编号]

具体要求：
1. [要求 1]
2. [要求 2]
3. [要求 3]

约束：
- 只实现这一个任务，不要修改其他模块
- 遵循项目的编码规范（参考 steering 文件）
- 包含单元测试，覆盖正常路径和边界情况
- 代码变更控制在 [N] 行以内

完成后请列出：
1. 修改了哪些文件
2. 新增了哪些函数/模块
3. 测试覆盖了哪些场景

┌─────────────────────────────────────────────────────────┐
│                   人工审查清单 v2.0                       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  □ 1. 设计合规性                                         │
│     - 代码是否符合 design.md 中的架构设计？               │
│     - 是否遵循了约定的设计模式？                          │
│     - 接口定义是否与设计文档一致？                        │
│                                                         │
│  □ 2. 安全性                                             │
│     - 是否有 SQL 注入、XSS、CSRF 风险？                  │
│     - 密钥/凭证是否硬编码？                              │
│     - 输入验证是否充分？                                  │
│     - 权限检查是否到位？                                  │
│                                                         │
│  □ 3. 性能                                               │
│     - 是否有 N+1 查询问题？                              │
│     - 是否有不必要的内存分配？                            │
│     - 算法复杂度是否合理？                                │
│     - 是否有潜在的阻塞操作？                              │
│                                                         │
│  □ 4. 测试覆盖                                           │
│     - 是否覆盖了验收标准中的所有场景？                    │
│     - 边界条件是否测试？                                  │
│     - 错误路径是否测试？                                  │
│     - 测试是否真正验证了行为（而非实现细节）？            │
│                                                         │
│  □ 5. 依赖管理                                           │
│     - 是否引入了不必要的新依赖？                          │
│     - 新依赖是否活跃维护？是否有已知漏洞？               │
│     - 依赖版本是否锁定？                                  │
│                                                         │
│  □ 6. 可读性与可维护性                                    │
│     - 命名是否清晰、一致？                                │
│     - 是否有充分的注释（特别是"为什么"而非"做什么"）？    │
│     - 代码结构是否符合项目约定？                          │
│     - 是否有重复代码可以提取？                            │
│                                                         │
│  □ 7. 范围控制                                           │
│     - AI 是否只修改了任务要求的部分？                     │
│     - 是否有"顺手"做的额外改动？                         │
│     - 是否修改了不应该修改的文件？                        │
│                                                         │
└─────────────────────────────────────────────────────────┘

# 步骤 1：查看 AI 的所有改动
git diff --stat          # 概览改了哪些文件
git diff                 # 逐行查看变更
 
# 步骤 2：确认范围
# 检查是否只修改了任务要求的文件
# 如果 AI "顺手"改了其他文件，考虑是否需要回退
 
# 步骤 3：逐文件审查
git diff -- src/sync_engine.rs    # 审查核心逻辑
git diff -- tests/                # 审查测试
 
# 步骤 4：运行测试
cargo test                        # Rust 项目
npm test                          # Node.js 项目
pytest                            # Python 项目
 
# 步骤 5：确认后提交
git add -p                        # 交互式暂存，逐块确认
git commit -m "feat: Task 3.1 - 实现文件哈希计算函数
 
- 使用 SHA-256 流式计算
- 支持大文件（>4GB）
- 包含 8 个单元测试
 
Refs: Task 3.1, AC 5.1"

请审查你刚才为 Task [编号] 生成的代码，重点检查：

1. 安全性：是否有注入、泄露、权限绕过风险？
2. 边界情况：空输入、超大输入、并发访问是否处理？
3. 错误处理：是否所有错误路径都有合理处理？
4. 性能：是否有 O(n²) 或更差的算法？是否有不必要的内存拷贝？
5. 一致性：是否与项目现有代码风格一致？

对于每个发现的问题，请说明：
- 问题描述
- 严重程度（高/中/低）
- 建议的修复方案

┌──────────────────────────────────────────────────┐
│              审查-修正循环                         │
├──────────────────────────────────────────────────┤
│                                                  │
│  第 1 轮：AI 生成 → 人工审查                      │
│  ├── 通过 → 提交，进入下一个任务                  │
│  └── 不通过 → 记录问题，进入第 2 轮               │
│                                                  │
│  第 2 轮：AI 修正 → 人工审查                      │
│  ├── 通过 → 提交                                 │
│  └── 不通过 → 进入第 3 轮                         │
│                                                  │
│  第 3 轮：AI 修正 → 人工审查                      │
│  ├── 通过 → 提交                                 │
│  └── 不通过 → ⚠️ 停止！需要人工介入               │
│      ├── 重新审视任务拆分是否合理                  │
│      ├── 检查设计文档是否有歧义                    │
│      ├── 考虑手动实现关键部分                      │
│      └── 或者拆分为更小的子任务                    │
│                                                  │
└──────────────────────────────────────────────────┘

# ❌ 模糊的修正指示
"这个有 bug，修一下"

# ✅ 精确的修正指示
"Task 3.1 的代码有以下问题需要修正：

1. [高] sync_engine.rs 第 45 行：当文件大小为 0 时，
   hash_file() 返回空字符串而非零字节的 SHA-256 哈希值。
   修正：对空文件也应计算正确的哈希值。

2. [中] sync_engine.rs 第 78 行：缓冲区大小硬编码为 4096，
   对于大文件效率低。
   修正：使用 64KB 缓冲区，或从配置读取。

3. [低] 测试文件缺少对符号链接文件的测试。
   修正：添加一个测试用例验证符号链接的处理。

请只修正以上问题，不要改动其他代码。"

方式 A：主分支直接提交（个人项目/小团队）
─────────────────────────────────────────
main: ──●──●──●──●──●──●──
        T1  T2  T3  T4  T5  T6
        每个任务一个 commit

方式 B：功能分支 + PR（团队协作）
─────────────────────────────────────────
main:    ──────────────●──────────────●──
                       ↑              ↑
feature/sync: ──●──●──●┘              │
               T1  T2  T3             │
feature/ui:    ──────●──●──●──●──────┘
                     T4  T5  T6  T7

方式 C：Git Worktrees 并行开发（高级）
─────────────────────────────────────────
worktree-1/: AI 执行 Task A（独立目录）
worktree-2/: AI 执行 Task B（独立目录）
worktree-3/: 人工审查和修正（独立目录）
→ 三个目录共享同一个 .git，互不干扰

# 创建 worktree 用于并行 AI 任务
git worktree add ../project-task-a feature/task-a
git worktree add ../project-task-b feature/task-b
 
# 在 worktree-a 中让 AI 执行 Task A
cd ../project-task-a
claude "执行 Task 3.1：文件哈希计算"
 
# 同时在 worktree-b 中让另一个 AI 执行 Task B
cd ../project-task-b
claude "执行 Task 3.2：文件差异比较"
 
# 在主目录中审查两个任务的结果
cd ../project
git diff main..feature/task-a
git diff main..feature/task-b
 
# 审查通过后合并
git merge feature/task-a
git merge feature/task-b
 
# 清理 worktree
git worktree remove ../project-task-a
git worktree remove ../project-task-b

┌─────────────────────────────────────────────────────────┐
│                    70/30 人机协作边界                     │
├──────────────────────┬──────────────────────────────────┤
│   AI 擅长（~70%）     │   人类必须介入（~30%）            │
├──────────────────────┼──────────────────────────────────┤
│ 样板代码              │ 架构决策                          │
│ (CRUD, DTO, Schema)  │ (选择哪种方案、权衡取舍)          │
├──────────────────────┼──────────────────────────────────┤
│ 标准模式实现          │ 边缘场景处理                      │
│ (认证、分页、缓存)    │ (AI 容易遗漏的极端情况)           │
├──────────────────────┼──────────────────────────────────┤
│ 测试用例生成          │ 性能优化                          │
│ (单元测试、集成测试)  │ (需要 profiling 和实测数据)       │
├──────────────────────┼──────────────────────────────────┤
│ 文档生成              │ 安全审查                          │
│ (API 文档、README)    │ (AI 可能引入隐蔽漏洞)            │
├──────────────────────┼──────────────────────────────────┤
│ 代码重构              │ 用户体验细节                      │
│ (提取函数、重命名)    │ (微交互、动画、手感)              │
├──────────────────────┼──────────────────────────────────┤
│ 数据转换              │ 业务规则验证                      │
│ (格式转换、序列化)    │ (领域专家才能判断的逻辑)          │
├──────────────────────┼──────────────────────────────────┤
│ 配置文件生成          │ 第三方集成调试                    │
│ (CI/CD, Docker)       │ (API 行为与文档不符时)            │
└──────────────────────┴──────────────────────────────────┘

当识别到"30% 区域"时：

策略 1：人工接管关键部分
─────────────────────────
让 AI 生成框架代码，人工填充关键逻辑。
例如：AI 生成认证中间件的结构，人工编写 token 验证逻辑。

策略 2：AI 生成 + 人工精调
─────────────────────────
让 AI 生成初版，人工基于实测数据调整。
例如：AI 生成缓存策略，人工根据 profiling 结果调整 TTL 和淘汰策略。

策略 3：人工设计 + AI 实现
─────────────────────────
人工做出关键决策并写入设计文档，AI 按设计实现。
例如：人工决定使用乐观锁处理并发，AI 实现具体的锁机制。

策略 4：拆分为更小的任务
─────────────────────────
将复杂任务拆分，让 AI 处理确定性部分，人工处理判断性部分。
例如：将"实现支付流程"拆分为"生成支付表单"（AI）和"实现风控规则"（人工）。

┌──────────────────────────────────────────────────┐
│         SonarQube + Claude Code 自主审查循环       │
├──────────────────────────────────────────────────┤
│                                                  │
│  ① AI Agent 生成代码                              │
│       ↓                                          │
│  ② 触发 SonarQube 扫描                           │
│       ↓                                          │
│  ③ AI Agent 通过 MCP 获取扫描结果                 │
│       ↓                                          │
│  ④ 质量门通过？                                   │
│     ├── 是 → 提交代码                             │
│     └── 否 → AI Agent 自动修复 → 回到 ②           │
│                                                  │
│  人工审查点：质量门通过后，人工做最终确认           │
│                                                  │
└──────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│              多 Agent 并行执行                        │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Agent 1 (Worktree A)     Agent 2 (Worktree B)     │
│  ┌──────────────┐         ┌──────────────┐         │
│  │ Task 3.1     │         │ Task 3.2     │         │
│  │ 文件哈希计算  │         │ 文件差异比较  │         │
│  └──────┬───────┘         └──────┬───────┘         │
│         ↓                        ↓                  │
│  ┌──────────────┐         ┌──────────────┐         │
│  │ 人工审查 3.1 │         │ 人工审查 3.2 │         │
│  └──────┬───────┘         └──────┬───────┘         │
│         ↓                        ↓                  │
│  ┌──────────────────────────────────────┐          │
│  │        合并到主分支                    │          │
│  │   解决可能的合并冲突                   │          │
│  └──────────────────────────────────────┘          │
│                     ↓                               │
│  ┌──────────────────────────────────────┐          │
│  │  Agent 3: Task 3.3（依赖 3.1 + 3.2） │          │
│  └──────────────────────────────────────┘          │
│                                                     │
│  注意：有依赖关系的任务必须串行执行                   │
│                                                     │
└─────────────────────────────────────────────────────┘

开发者的角色转变：
─────────────────
从：逐行编写代码的"程序员"
到：指导 AI Agent 的"技术总监"

日常工作模式：
─────────────────
上午：
  1. 审查昨天 AI 生成的代码（30 分钟）
  2. 规划今天的任务（15 分钟）
  3. 启动 AI 执行第一批任务

中午：
  4. 审查上午的产出
  5. 处理"30% 区域"的问题
  6. 启动下午的任务

下午：
  7. 审查并合并代码
  8. 处理集成问题
  9. 规划明天的任务

- [ ] 3. 同步引擎核心
  - [ ] 3.1 实现文件哈希计算函数
  - [ ] 3.2 实现文件差异比较模块
  - [ ] 3.3 实现增量同步算法
  - [ ] 3.4 实现冲突检测逻辑
  - [ ] 3.5 实现冲突解决策略

请执行 Task 3.1：实现文件哈希计算函数。

参考 design.md 第 3.1 节：
- 使用 SHA-256 算法
- 支持流式计算（文件可能 > 4GB）
- 返回十六进制字符串

验收标准：
- AC 5.1: 对相同文件内容始终返回相同哈希值
- AC 5.2: 对不同文件内容返回不同哈希值
- AC 5.3: 支持空文件

只实现这一个函数，不要实现差异比较或同步逻辑。

审查发现：
✅ 算法正确，使用了 SHA-256
✅ 流式读取，64KB 缓冲区
✅ 包含 5 个单元测试
⚠️ 问题 1：缓冲区大小硬编码，建议改为可配置
⚠️ 问题 2：缺少对符号链接的处理
❌ 问题 3：错误处理使用了 unwrap()，不符合项目规范

Task 3.1 审查发现 3 个问题，请修正：

1. [低] 缓冲区大小硬编码为 65536
   → 改为从常量定义，方便后续调整

2. [中] 未处理符号链接文件
   → 添加对符号链接的处理：跟随链接计算目标文件的哈希

3. [高] 第 23 行和第 45 行使用了 unwrap()
   → 改为 ? 操作符，返回 Result<String, SyncError>
   → 参考项目的错误处理规范（steering 文件）

只修正以上问题，不要改动其他代码。

✅ 所有问题已修正
✅ 测试全部通过（7 个测试）
✅ clippy 无警告
→ 提交并标记 Task 3.1 完成

git add src/hash.rs tests/hash_test.rs
git commit -m "feat(sync): Task 3.1 - 实现文件哈希计算函数
 
- SHA-256 流式计算，支持大文件
- 处理符号链接（跟随链接）
- 处理空文件
- 7 个单元测试覆盖正常路径和边界情况
 
Refs: Task 3.1, AC 5.1, AC 5.2, AC 5.3"