# Good Iteration Habits

> 良好的软件迭代习惯

- Skill: `lstm-kirigaya/good-iteration-habits` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lstm-kirigaya/good-iteration-habits`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lstm-kirigaya/good-iteration-habits/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lstm-kirigaya (https://skillmd.com/u/lstm-kirigaya)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lstm-kirigaya/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：接口调研

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

| 需要的后端能力 | 是否已有接口 | 已有接口路径 | 是否满足需求 | 备注 |
|---------------|-------------|-------------|-------------|-----|
| 用户查询 | ✅ | 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 组件或页面时，确保功能完整性，不丢失任何交互或数据展示功能。**

**适用场景：**
- 用户要求重构某个功能模块
- 优化页面布局或组件样式
- 重做某个交互功能

**执行流程：**

详细指南请参考：[重构功能完整性验证](./refactoring-with-verification/SKILL.md)

#### 步骤 1：获取当前状态
- 截图记录重构前的页面状态
- 分析相关代码实现

#### 步骤 2：功能清单化
创建两个表格：
- **表格 A**：所有可交互功能点（按钮、链接、表单等）
- **表格 B**：所有数据展示功能点（文本、列表、图表等）

#### 步骤 3：用户确认
向用户展示功能清单，明确：
- 哪些功能保留
- 哪些功能修改
- 哪些功能删除

#### 步骤 4：执行重构
根据确认的范围修改代码

#### 步骤 5：功能验证
- 截图对比
- 逐一测试交互功能
- 逐一验证数据展示

#### 步骤 6：对比检查
确保：
- 所有保留功能正常工作
- 无意外删除的功能
- 新功能按需求实现

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

---

## 迭代工作流程

### 新需求开发流程

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

### 重构优化流程

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

---

## 检查清单

### 新需求开发

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

### 重构优化

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