# Incremental Implementation

> Use when implementing any feature or change that touches more than one file, when about to write a large amount of code at once, or when a task feels too big to land in one step.

- Skill: `just-silver/incremental-implementation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add just-silver/incremental-implementation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/just-silver/incremental-implementation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Just-Silver (https://skillmd.com/u/just-silver)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/just-silver/incremental-implementation

---


# Incremental Implementation（增量实现）

## Overview

薄垂直切片：实现一片、测一片、验一片、存档，再扩。整功能一遍写完即把所有 bug 打包，最后只能靠运气。每片落地时系统保持可工作、可测试、可回退。

## When to Use

- 任何多文件改动、新功能、重构
- 想一口气写超 ~100 行再测时
- 任务大到一次落不了地时

**When NOT to use:**

- 单文件单函数、范围已最小的改动

## 增量循环

```
Implement → Test → Verify → 存档 → 下一片
    ▲                              │
    └──── 每片独立可回退 ───────────┘
```

**存档（checkpoint）= 工作树可回退状态**：正式 `git commit` / `git stash` / 暂存 diff 存档均可。**是否产生 git commit 由用户决定**——用户没要求提交时，不要替用户制造提交（那是改变仓库状态的额外行为）；用户要求一片一提交时才提交。详见「实现纪律」的"存档 ≠ 自动提交"。

每片：实现最小完整功能 → 跑测试（无则写）→ 确认片可用（测试绿、构建过、手工验）→ 存档 → 下一片接着来不重开。

## 切片三法

**纵向切片（首选）**：一次一整条路，不按层切。

```
片1：创建（存储 + 接口 + 最简界面）→ 端到端可创建
片2：列表（查询 + 接口 + 界面）→ 可看
片3：编辑 → 可改
片4：删除 + 确认 → 闭环
```

每片都是可用功能，不是半层脚手架。

**契约先行（并行时）**：

```
片0：定接口契约（类型/字段/错误码）
片1a：后端按契约实现 + 接口测试
片1b：前端按契约 mock 实现
片2：联调端到端
```

**风险先行**：最不确定的先啃。片1证伪最高风险，失败早暴露，不把成本押后。

## 实现纪律

- **先简后对**：动手前问"最简能跑的是什么"；写完问"能更少行吗、抽象挣回复杂度了吗、是不是为假想需求造的"——先天真正确的版本，测绿再优化
- **范围纪律**：只碰任务要的；顺手重构/清 import/加"有用"功能一律另起任务，不混入本片
- **一次一事**：一片只改一个逻辑；加功能、重构、改配置拆成不同片，不混入同片
- **片片可编译**：每片落地构建过、旧测试全绿，不留半红过夜
- **未完成功能打旗**：需合主干但用户不可见即特性开关包住，默认关；每旗有主有到期， rollout 完清旗清死代码
- **安全默认**：新行为默认保守（关/拒/最小），显式 opt-in 才放开
- **回退友好**：新增好回退，改存量小而散，数据迁移配反向迁移
- **存档 ≠ 自动提交**："一片一存档"的存档指**工作树可回退状态**（`git commit` / `git stash` / 暂存 diff 存档均可）；**是否产生 git commit 由用户决定**——用户没要求提交时，不要替用户制造 git commit（自动 commit 是改变仓库状态的额外行为）；用户明确要求"一片一提交"时才提交，此时信息要清、可独立 revert

## Quick Reference

| 场景 | 动作 |
|------|------|
| 多文件功能 | 纵向切片，一片一可用 |
| 并行开发 | 片0先定契约再分头 |
| 风险不明 | 片1啃最高风险 |
| 想写超100行 | 停，切片，先验当前 |
| 5文件改挂 | 二分回退定位；平时一片一存档即可回退，不遭此罪 |
| 顺手想改别的 | 记下另起任务，不混本片 |

## Common Rationalizations

| Excuse | Reality |
|--------|---------|
| "全写完再统一测" | bug 打包互相掩盖，定位成本翻倍；一片一绿才是省时间 |
| "这片太小了，攒大了一起交" | 小即回退点；攒大即丢回退点，出事二分到哭 |
| "顺手重构一下" | 混入即污染回退；重构另起一片，独立可 revert |
| "先写复杂版一步到位" | 一步到位多半走错路；天真版测绿再加复杂度，加错了也好回 |
| "开关以后再清" | 无到期开关即永久税；建旗即定主 + 到期， rollout 完清 |
| "300行了，写完这段再验" | 100 行无验证即债；停，先固化能跑的部分 |

## Red Flags — STOP

- 超 ~100 行无验证还在写
- 一片跨多逻辑（功能 + 重构 + 配置一锅）
- 主干半红过夜（构建挂/旧测试红着合）
- 无到期特性开关进主干
- 数据迁移无反向
- 顺手改动混入本片（污染可回退边界）
- 用户没要求提交却擅自批量 git commit

**以上任一出现 → 停手，切片/存档/清范围后再往下写。**

## Verification

- [ ] 每片纵向可用（端到端走得通）
- [ ] 每片测试绿 + 构建过 + 手工验
- [ ] 每片有可回退存档（git commit 仅当用户要求时；提交则信息清、可独立 revert）
- [ ] 开关有主有到期，默认关
- [ ] 数据迁移有反向
- [ ] 存档内无范围外改动