Good Iteration Habits

良好的软件迭代习惯

软件迭代过程中的最佳实践，帮助团队保持高效、可持续的开发节奏，减少技术债务和功能冲突。

核心原则

复用优于新建，清晰胜于复杂。

在实现新功能前，先审视已有资源；在修改代码前，先理解现有依赖。

三大习惯

习惯一：测试优先

项目初始化时必做检查：

1. 检查当前项目是否已有测试集

   • 查找测试文件（如 *.test.js, *.spec.ts, tests/ 目录等）
   • 检查 package.json 中的 test scripts
   • 检查 CI/CD 配置中的测试步骤

2. 如果没有测试集：

   • 参考测试集构建指南：./build-test-suite/SKILL.md
   • 优先构建后端功能测试
   • 确保核心功能有测试覆盖后再继续开发

3. 每次提交前：

   • 运行全部测试
   • 确保测试通过后再提交

习惯二：复用现有接口

实现新需求时，优先使用已存在的后端接口，避免随意创建新接口。

执行流程：

步骤 1：需求拆解

当用户提出新需求时，先进行拆解分析：

需求：[用户描述的功能]

拆解表格：
| 需求点 | 前端功能 | 需要的后端能力 | 优先级 |
|-------|---------|---------------|-------|
| ...   | ...     | ...           | P0/P1 |

步骤 2：接口调研

针对拆解表格，逐个调研：

步骤 3：决策输出

基于调研结果，给出实现方案：

推荐方案：
- 复用接口：GET /api/users, POST /api/export
- 扩展接口：POST /api/export（添加 xx 字段）
- 新建接口：无
- 实现复杂度：低

原则：

• ✅ 能用现有接口组合实现的，不新建接口
• ✅ 现有接口需要小改动能满足的，优先扩展
• ⚠️ 必须新建接口时，需要充分说明理由
• ❌ 禁止未经调研直接创建新接口

习惯三：影响评估

保证新需求不会破坏现有功能，如有冲突需用户知情决策。

执行流程：

步骤 1：依赖分析

分析新需求会触及的功能模块：

新需求：[功能描述]

影响范围分析：
| 触及模块 | 当前功能 | 新需求改动 | 冲突风险 | 建议处理 |
|---------|---------|-----------|---------|---------|
| UserService | 查询用户信息 | 添加字段过滤 | 低 | 直接扩展 |
| Auth API | 登录鉴权 | 修改 token 结构 | 高 | 需用户确认 |
| ... | ... | ... | ... | ... |

步骤 2：风险评估

步骤 3：冲突报告（高风险时）

当发现新需求与现有系统存在冲突时，暂停代码生成，输出冲突报告：

⚠️ 功能冲突报告

新需求：[功能描述]

冲突点分析：
| 冲突模块 | 当前实现 | 新需求要求 | 冲突说明 | 可选方案 |
|---------|---------|-----------|---------|---------|
| OrderService | 订单状态：pending/paid/delivered | 新增 canceling 状态 | 状态机逻辑需重构 | A: 扩展状态机 B: 新建状态字段 |
| Payment API | 同步支付回调 | 异步支付通知 | 回调机制变更 | A: 兼容两种模式 B: 仅支持异步 |

影响范围：
- 受影响的模块：OrderService, PaymentService, NotificationService
- 受影响的接口：3 个
- 预估重构成本：2-3 天

建议：
[给出推荐的解决方案]

请确认处理方式后再继续...

原则：

• 功能影响必须可预期、可控制
• 高风险改动必须获得用户明确同意
• 禁止在用户不知情的情况下破坏现有功能

习惯四：重构验证

重构或优化 UI 组件或页面时，确保功能完整性，不丢失任何交互或数据展示功能。

适用场景：

• 用户要求重构某个功能模块
• 优化页面布局或组件样式
• 重做某个交互功能

执行流程：

详细指南请参考：重构功能完整性验证

步骤 1：获取当前状态

• 截图记录重构前的页面状态
• 分析相关代码实现

步骤 2：功能清单化

创建两个表格：

• 表格 A：所有可交互功能点（按钮、链接、表单等）
• 表格 B：所有数据展示功能点（文本、列表、图表等）

步骤 3：用户确认

向用户展示功能清单，明确：

• 哪些功能保留
• 哪些功能修改
• 哪些功能删除

步骤 4：执行重构

根据确认的范围修改代码

步骤 5：功能验证

• 截图对比
• 逐一测试交互功能
• 逐一验证数据展示

步骤 6：对比检查

确保：

• 所有保留功能正常工作
• 无意外删除的功能
• 新功能按需求实现

原则：

• ✅ 重构前必须先记录当前功能清单
• ✅ 重构后必须验证所有保留功能
• ❌ 禁止在未确认功能清单的情况下直接重构
• ❌ 禁止在验证通过前认为重构完成

迭代工作流程

新需求开发流程

接收需求
    ↓
[习惯一] 检查测试集 → 无则先构建测试
    ↓
[习惯二] 需求拆解 → 表格罗列前端/后端功能点
    ↓
[习惯二] 接口调研 → 标记可复用/需扩展/需新建
    ↓
[习惯三] 影响评估 → 分析对现有功能的影响
    ↓
    ├─ 无冲突/低风险 → 正常实现
    └─ 高风险冲突 → 生成冲突报告，等待用户决策

重构优化流程

接收重构/优化需求
    ↓
[习惯四] 获取当前状态 → 截图 + 代码分析
    ↓
[习惯四] 功能清单化 → 列出所有交互和数据展示点
    ↓
[习惯四] 用户确认 → 展示功能清单并确认范围
    ↓
[习惯三] 影响评估 → 评估对关联功能的影响
    ↓
    ├─ 范围明确/无冲突 → 执行重构
    └─ 存在冲突/范围不清 → 澄清后再继续
    ↓
[习惯四] 功能验证 → 截图 + 交互测试 + 对比检查
    ↓
    ├─ 功能完整 → 完成
    └─ 功能丢失 → 修复后重新验证

检查清单

新需求开发

• 项目是否有测试集（无则参考 ./build-test-suite/SKILL.md）
• 新需求是否已拆解为前端/后端功能点表格
• 是否已调研现有接口，优先复用而非新建
• 是否已评估对现有功能的影响
• 高风险改动是否已生成冲突报告并获用户确认
• 提交前是否已运行全部测试

重构优化

• 是否已获取重构前截图（参考 ./refactoring-with-verification/SKILL.md）
• 是否已列出所有交互功能点（表格 A）
• 是否已列出所有数据展示点（表格 B）
• 是否与用户确认功能清单和重构范围
• 是否已评估对关联功能的影响
• 重构后是否逐一验证所有保留功能
• 是否获取重构后截图进行对比
• 是否确认无功能被意外删除
• 提交前是否已运行全部测试