| name | good-iteration-habits |
| description | 良好的软件迭代习惯指南。Use when planning or executing software development iterations for: (1) Initializing projects with proper test coverage checks, (2) Implementing new features by reusing existing APIs instead of creating new ones, (3) Analyzing feature dependencies before implementation, (4) Preventing feature conflicts through dependency analysis, (5) Breaking down requirements into frontend/backend components and evaluating existing implementations, (6) Refactoring UI components while preserving all functionality. |
良好的软件迭代习惯
软件迭代过程中的最佳实践，帮助团队保持高效、可持续的开发节奏，减少技术债务和功能冲突。
核心原则
复用优于新建，清晰胜于复杂。
在实现新功能前，先审视已有资源；在修改代码前，先理解现有依赖。
三大习惯
习惯一：测试优先
项目初始化时必做检查：
-
检查当前项目是否已有测试集
- 查找测试文件（如
*.test.js, *.spec.ts, tests/ 目录等）
- 检查
package.json 中的 test scripts
- 检查 CI/CD 配置中的测试步骤
-
如果没有测试集：
- 参考测试集构建指南：
./build-test-suite/SKILL.md
- 优先构建后端功能测试
- 确保核心功能有测试覆盖后再继续开发
-
每次提交前：
习惯二：复用现有接口
实现新需求时，优先使用已存在的后端接口，避免随意创建新接口。
执行流程：
步骤 1：需求拆解
当用户提出新需求时，先进行拆解分析：
需求：[用户描述的功能]
拆解表格：
| 需求点 | 前端功能 | 需要的后端能力 | 优先级 |
|-------|---------|---------------|-------|
| ... | ... | ... | P0/P1 |
步骤 2：接口调研
针对拆解表格，逐个调研：
| 需要的后端能力 | 是否已有接口 | 已有接口路径 | 是否满足需求 | 备注 |
|---|
| 用户查询 | ✅ | GET /api/users | ✅ 满足 | - |
| 数据导出 | ✅ | POST /api/export | ⚠️ 部分满足 | 需要添加字段 |
| 权限验证 | ❌ | - | - | 需新建 |
步骤 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：对比检查
确保：
- 所有保留功能正常工作
- 无意外删除的功能
- 新功能按需求实现
原则：
- ✅ 重构前必须先记录当前功能清单
- ✅ 重构后必须验证所有保留功能
- ❌ 禁止在未确认功能清单的情况下直接重构
- ❌ 禁止在验证通过前认为重构完成
迭代工作流程
新需求开发流程
接收需求
↓
[习惯一] 检查测试集 → 无则先构建测试
↓
[习惯二] 需求拆解 → 表格罗列前端/后端功能点
↓
[习惯二] 接口调研 → 标记可复用/需扩展/需新建
↓
[习惯三] 影响评估 → 分析对现有功能的影响
↓
├─ 无冲突/低风险 → 正常实现
└─ 高风险冲突 → 生成冲突报告，等待用户决策
重构优化流程
接收重构/优化需求
↓
[习惯四] 获取当前状态 → 截图 + 代码分析
↓
[习惯四] 功能清单化 → 列出所有交互和数据展示点
↓
[习惯四] 用户确认 → 展示功能清单并确认范围
↓
[习惯三] 影响评估 → 评估对关联功能的影响
↓
├─ 范围明确/无冲突 → 执行重构
└─ 存在冲突/范围不清 → 澄清后再继续
↓
[习惯四] 功能验证 → 截图 + 交互测试 + 对比检查
↓
├─ 功能完整 → 完成
└─ 功能丢失 → 修复后重新验证
检查清单
新需求开发
重构优化
